` to
-// `
` for example.
-// We're doing this so that we can set a much more aggressive
-// Cache-Control for assets and a CDN surrogate-key that doesn't
-// soft-purge on every deployment.
+// Markdown image URLs include a cache-busting path part, for example
+// /assets/foo/bar.png becomes /assets/cb-123467/foo/bar.png.
+// That path lets assets use aggressive Cache-Control and a Fastly surrogate key
+// that avoids soft purges on every deployment.
const regex = /\/cb-\d+\//
@@ -20,27 +15,16 @@ export default function assetPreprocessing(
next: NextFunction,
) {
if (req.path.startsWith('/assets/')) {
- // We didn't use to have a rule about all image assets must be
- // lower case. So we've exposed things like:
- // 
which means they could
- // get a 404 if the file is actually named `foobar.png`.
+ // Mixed-case asset URLs can 404 when the file on disk is lowercase.
if (req.url !== req.url.toLowerCase()) {
- // The reason for doing a redirect instead rewriting the
- // `req.url` attribute is that we don't want encourage this.
- // By forcing this to be a redirect, it means we only serve
- // 1 single file. All other requests will be redirects.
- // Otherwise someone might trigger too much bypassing of the CDN.
+ // Redirecting instead of rewriting req.url serves one canonical file and protects CDN hit rates.
return res.safeRedirect(req.url.toLowerCase())
}
- // We're only confident enough to set the *manual* surrogate key if the
- // asset contains the cache-busting piece.
+ // Only cache-busted assets can use the manual surrogate key safely.
if (regex.test(req.url)) {
- // We remove it so that when `express.static()` runs, it can
- // find the file on disk by its original name.
+ // express.static() needs the original file path on disk.
req.url = req.url.replace(regex, '/')
- // The Cache-Control is managed by the configuration
- // for express.static() later in the middleware.
}
}
return next()
diff --git a/src/assets/middleware/dynamic-assets.ts b/src/assets/middleware/dynamic-assets.ts
index c95d53f7f7aa..f41d500387c6 100644
--- a/src/assets/middleware/dynamic-assets.ts
+++ b/src/assets/middleware/dynamic-assets.ts
@@ -13,35 +13,20 @@ import { createLogger } from '@/observability/logger'
const logger = createLogger(import.meta.url)
-/**
- * This is the indicator that is a virtual part of the URL.
- * Similar to `/cb-1234/` in asset URLs, it's just there to tell the
- * middleware that the image can be aggressively cached. It's not
- * part of the actual file-on-disk path.
- * Similarly, `/mw-1000/` is virtual and will be observed and removed from
- * the pathname before trying to look it up as disk-on-file.
- * The exact pattern needs to match how it's set in whatever Markdown
- * processing code that might make dynamic asset URLs.
- * So if you change this, make sure you change the code that expects
- * to be able to inject this into the URL.
- */
+// Markdown processing injects a max-width segment such as /mw-1440/ into dynamic asset URLs.
+// Like /cb-1234/, it marks cacheable work and is not part of the file path on disk.
+// Keep this pattern in sync with the Markdown code that builds dynamic asset URLs.
const maxWidthPathPartRegex = /\/mw-(\d+)\//
-/**
- *
- * Why not any free number? If we allowed it to be any integer number
- * someone would put our backend servers at risk by doing something like:
- *
- * const makeURL = () => `${BASE}/assets/mw-${Math.floor(Math.random()*1000)}/foo.png`
- * await Promise.all([...Array(10000).keys()].map(makeURL))
- *
- * Which would be lots of distinctly different and valid URLs that the
- * CDN can never really "protect us" on because they're too often distinct.
- *
- * At the moment, the only business need is for 1,000 pixels, so the array
- * only has one. But can change in the future and make this sentence moot.
- */
+// Restrict widths to product-supported sizes, so attackers cannot create many
+// distinct resize URLs that bypass CDN reuse.
const VALID_MAX_WIDTHS = [1440, 1000]
+// WebP effort 5 keeps output smaller without using sharp's slowest CPU setting.
+// CDN caching lets production pay the conversion cost once per image.
+// https://www.peterbe.com/plog/comparing-different-efforts-with-webp-in-sharp
+// Lossy WebP is acceptable because these images are rendered for viewing, not source editing.
+// Lossless output is slightly crisper but averages 1.8x larger.
+// Sharp's default 80% quality and lossy mode make our images 2.8x smaller than PNGs on average.
export default async function dynamicAssets(
req: ExtendedRequest,
res: Response,
@@ -53,39 +38,16 @@ export default async function dynamicAssets(
return res.status(405).type('text/plain').send('Method Not Allowed')
}
- // To protect from possible denial of service, we never allow what
- // we're going to do (the image file operation), if the whole thing
- // won't be aggressively cached.
- // If we didn't do this, someone making 2 requests, ...
- //
- // > GET /assets/images/site/logo.web?random=10476583
- // > GET /assets/images/site/logo.web?random=20196996
- //
- // ...would be treated as 2 distinct backend requests. Sure, each one
- // would be cached in the CDN, but that's not helping if someone does...
- //
- // while (true) {
- // startFetchThread(`/assets/images/site/logo.web?whatever=${rand()}`)
- // }
- //
- // So we "force" any deviation of the URL to a redirect to the canonical
- // URL (which, again, is heavily cached).
+ // Query strings create distinct dynamic asset URLs, so redirect them to the canonical cached URL.
if (Object.keys(req.query).length > 0) {
- // Cache the 404 so it won't be re-attempted over and over
+ // Cache the redirect so repeated noncanonical URLs do not keep reaching the backend.
defaultCacheControl(res)
- // This redirects to the same URL we're currently on, but with the
- // query string part omitted.
- // For example:
- //
- // > GET /assets/images/site/logo.web?foo=bar
- // < 302
- // < location: /assets/images/site/logo.web
- //
+ // /assets/images/site/logo.webp?foo=bar redirects to /assets/images/site/logo.webp.
return res.safeRedirect(302, req.path)
}
- // From PNG to WEBP, if the PNG exists
+ // Dynamic WebP files are generated from PNG sources on demand.
if (req.path.endsWith('.webp')) {
const { url, maxWidth, error } = deconstructImageURL(req.path)
if (error) {
@@ -104,49 +66,15 @@ export default async function dynamicAssets(
}
}
- // The default in sharp.webp() for effort is 4. It's a sensible
- // balance between time and compression.
- // If you make it low, it makes the webp conversion faster.
- // If you make it high, the webp conversion is slower but the
- // resulting WEBP file are smaller.
- // Given that our App Service containers aren't very strong in
- // terms of CPU, we avoid the highest effort. But given how
- // well our CDN protects repeated requests for the same image,
- // we can pay this cost once and reap it for a very long time.
- // Be mindful at the highest (6), it can be extremely slow so
- // let's avoid that for now.
- //
- // For more information about the effort option, see:
- // https://www.peterbe.com/plog/comparing-different-efforts-with-webp-in-sharp
- //
let effort = 5
if (process.env.NODE_ENV === 'test') {
- // When running tests, we want to make the conversion as fast
- // as possible because the resulting WEBP buffer will most
- // likely never be enjoyed by network or human eyes.
+ // Tests need fast conversion because the WebP buffer is not user-visible.
effort = 1
} else if (process.env.NODE_ENV === 'development') {
- // If you're doing local development (or review), the
- // network is not precious (localhost:4000) and you have no
- // CDN to cache it for you. Make it low but not too unrealistically
- // low.
+ // Development has no CDN reuse, so reduce conversion CPU cost.
effort = 1
}
- // Note that by default, sharp will use a lossy compression.
- // (i.e. `{lossless: false}` in the options)
- // The difference is that a lossless image is slightly crisper
- // but becomes on average 1.8x larger.
- // Given how we serve images, no human would be able to tell the
- // difference simply by looking at the image as it appears as an
- // image tag in the web page.
- // Also given that rendering-for-viewing is the "end of the line"
- // for the image meaning it just ends up being viewed and not
- // resaved as a source file. If we had intention to overwrite all
- // original PNG source files to WEBP, we should consider lossless
- // to preserve as much quality as possible at the source level.
- // The default quality is 80% which, combined with `lossless:false`
- // makes our images 2.8x smaller than the average PNG.
const buffer = await image.webp({ effort }).toBuffer()
assetCacheControl(res)
return res.type('image/webp').send(buffer)
@@ -162,23 +90,13 @@ export default async function dynamicAssets(
}
}
- // Cache the 404 so it won't be re-attempted over and over
+ // Cache the 404 so repeated missing assets do not keep reaching the backend.
defaultCacheControl(res)
- // There's a preceeding middleware that sets the Surrogate-Key to
- // "manual-purge" based on the URL possibly having the `/cb-xxxxx/`
- // checksum in it. But, if it failed, we don't want that. So
- // undo that if it was set.
- // It's handy too to not overly cache 404s in the CDN because
- // it could be that the next prod deployment fixes the missing image.
- // For example, a PR landed that introduced the *reference* to the image
- // but forgot to check in the new image, then a follow-up PR adds the image.
+ // Missing dynamic assets use the language surrogate key, not manual-purge, so a later deploy can add the image.
setFastlySurrogateKey(res, makeLanguageSurrogateKey(), true)
- // Don't use something like `next(404)` because we don't want a fancy
- // HTML "Page not found" page response because a failed asset lookup
- // is impossibly a typo in the browser address bar or an accidentally
- // broken link, like it might be to a regular HTML page.
+ // Keep missing asset responses plain text instead of rendering the HTML page-not-found response.
res.status(404).type('text/plain').send('Asset not found')
}
diff --git a/src/assets/middleware/static-asset-caching.ts b/src/assets/middleware/static-asset-caching.ts
index 250aa2b85d00..75fb6b03f1e0 100644
--- a/src/assets/middleware/static-asset-caching.ts
+++ b/src/assets/middleware/static-asset-caching.ts
@@ -14,8 +14,7 @@ export default function setStaticAssetCaching(
return next()
}
-// True if the URL is known to contain some pattern of a checksum that
-// would make it intelligently different if its content has changed.
+// Checksummed URLs can keep manual surrogate keys because content changes produce new URLs.
function isChecksummed(path: string) {
if (path.startsWith('/assets/cb-')) return true
if (path.startsWith('/_next/static')) {
diff --git a/src/assets/scripts/deleted-assets-pr-comment.ts b/src/assets/scripts/deleted-assets-pr-comment.ts
index 55f129b40ca1..88626e24875b 100755
--- a/src/assets/scripts/deleted-assets-pr-comment.ts
+++ b/src/assets/scripts/deleted-assets-pr-comment.ts
@@ -8,7 +8,7 @@ if (!GITHUB_TOKEN) {
throw new Error(`GITHUB_TOKEN environment variable not set`)
}
-// When this file is invoked directly from action as opposed to being imported
+// Direct workflow execution writes the PR comment body to an action output.
if (import.meta.url.endsWith(process.argv[1])) {
const owner = context.repo.owner
const repo = context.payload.repository?.name || ''
@@ -27,7 +27,6 @@ type MainArgs = {
}
async function main({ owner, repo, baseSHA, headSHA }: MainArgs) {
const octokit = getOctokit(GITHUB_TOKEN as string)
- // get the list of file changes from the PR
const response = await octokit.rest.repos.compareCommitsWithBasehead({
owner,
repo,
@@ -40,8 +39,7 @@ async function main({ owner, repo, baseSHA, headSHA }: MainArgs) {
throw new Error('No files found in the PR')
}
- // Auto-generated asset directories managed by sync pipelines.
- // These are deleted and recreated on each sync, so deletions are expected.
+ // Sync pipelines delete and recreate these auto-generated asset directories.
const AUTO_GENERATED_ASSET_DIRS = ['assets/images/help/copilot/copilot-sdk/']
const oldFilenames = []
@@ -50,10 +48,8 @@ async function main({ owner, repo, baseSHA, headSHA }: MainArgs) {
if (!filename.startsWith('assets')) continue
if (AUTO_GENERATED_ASSET_DIRS.some((dir) => filename.startsWith(dir))) continue
if (status === 'removed') {
- // Bad
oldFilenames.push(filename)
} else if (status === 'renamed') {
- // Also bad
const previousFilename = file.previous_filename
oldFilenames.push(previousFilename)
}
diff --git a/src/assets/scripts/find-orphaned-assets.ts b/src/assets/scripts/find-orphaned-assets.ts
index 15143e4d7fc2..e85c54e87aaa 100755
--- a/src/assets/scripts/find-orphaned-assets.ts
+++ b/src/assets/scripts/find-orphaned-assets.ts
@@ -1,9 +1,4 @@
-// [start-readme]
-//
-// Print a list of all the asset files that can't be found mentioned
-// in any of the source files (content & code).
-//
-// [end-readme]
+// Prints assets that no content or code file mentions.
import fs from 'fs'
import path from 'path'
@@ -79,7 +74,7 @@ const EXCEPTIONS = new Set([
'assets/images/social-cards/subscriptions-and-notifications.png',
'assets/images/social-cards/support.png',
'assets/images/social-cards/webhooks.png',
- // Hero images may not be used, but we keep them around for future use
+ // Hero images may be reused even when no source file mentions them.
'assets/images/banner-images/hero-1.png',
'assets/images/banner-images/hero-2.png',
'assets/images/banner-images/hero-3.png',
@@ -89,11 +84,7 @@ const EXCEPTIONS = new Set([
])
function isExceptionPath(imagePath: string) {
- // We also check for .DS_Store because any macOS user that has opened
- // a folder with images will have this on disk. It won't get added
- // to git anyway thanks to our .DS_Store.
- // But if we don't make it a valid exception, it can become inconvenient
- // to run this script locally.
+ // Local macOS image folders can contain .DS_Store files that are not tracked.
return (
EXCEPTIONS.has(imagePath) ||
path.basename(imagePath) === '.DS_Store' ||
@@ -131,10 +122,7 @@ async function main(opts: MainOptions) {
sourceFiles.push(...englishFiles)
if (!excludeTranslations) {
- // Need to have this so we can filter the translations files and avoid
- // including orphans. Because translations generally don't delete files.
- // When the English content renames something, you later end up with
- // 2 files in each translation repo.
+ // Translations keep files after English renames, so only search translated files that match English.
const englishRelativeFiles = new Set(
englishFiles.map((englishFile) => path.relative(languages.en.dir, englishFile)),
)
@@ -173,7 +161,6 @@ async function main(opts: MainOptions) {
),
)
}
- // Add exceptions
sourceFiles.push('.github/CONTRIBUTING.md')
sourceFiles.push('README.md')
if (verbose) {
@@ -213,8 +200,7 @@ async function main(opts: MainOptions) {
console.log(JSON.stringify([...allImages], undefined, 2))
} else {
for (const imagePath of [...allImages].sort((a, b) => a.localeCompare(b))) {
- // It's important to escape spaces if we're ever going to pipe this
- // to xargs.
+ // Quotes preserve paths with spaces when piped to xargs.
console.log(`"${imagePath}"`)
}
}
diff --git a/src/assets/scripts/list-image-sizes.ts b/src/assets/scripts/list-image-sizes.ts
index 34a4f8fcdd3f..8c37b9c6308e 100755
--- a/src/assets/scripts/list-image-sizes.ts
+++ b/src/assets/scripts/list-image-sizes.ts
@@ -1,8 +1,4 @@
-// [start-readme]
-//
-// This script lists all local image files, sorted by their dimensions.
-//
-// [end-readme]
+// Lists local image files by pixel area, largest first.
import { fileURLToPath } from 'url'
import path from 'path'
diff --git a/src/assets/scripts/validate-asset-images.ts b/src/assets/scripts/validate-asset-images.ts
index f799bee711c1..56269406427a 100755
--- a/src/assets/scripts/validate-asset-images.ts
+++ b/src/assets/scripts/validate-asset-images.ts
@@ -1,15 +1,5 @@
-// [start-readme]
-//
-// Makes sure that all the image assets in `assets/` are safe.
-//
-// Generally writers don't check in bogus/corrupt images but mistakes
-// can happen and it's ideally spotted in other processes such as
-// reviewing PR review environment.
-// This script also makes sure that all images really are what they're
-// called. For example, an image might be named `screenshot.png` but
-// it might actually be something mischievous.
-//
-// [end-readme]
+// Validates asset files for corrupt images, unsafe SVG content, and mismatched file types.
+// For example, screenshot.png must contain image/png data.
import fs from 'fs/promises'
import path from 'path'
@@ -24,12 +14,11 @@ import isSVG from 'is-svg'
const ASSETS_ROOT = path.resolve('assets')
const ROOT = path.dirname(ASSETS_ROOT)
-// We put images that are used by the React components in with the assets
-// directory. These aren't really content-contibuted.
+// React component images live under assets but are not content-contributed.
const EXCLUDE_DIR = path.join(ASSETS_ROOT, 'images', 'site')
const IGNORE_EXTENSIONS = new Set([
- // Currently has no known test for these
+ // CSV assets have no validator.
'.csv',
])
@@ -105,7 +94,7 @@ async function checkFile(filePath: string) {
}
if (ext === '.svg') {
- // Can't use `fileTypeFromFile` so have to check "manually"
+ // fileTypeFromFile cannot validate SVG, so parse the text content.
const content = await fs.readFile(filePath, 'utf-8')
if (!content.trim()) {
return [CRITICAL, filePath, 'file is empty']
@@ -133,8 +122,6 @@ async function checkFile(filePath: string) {
} else {
return [WARNING, filePath, `Don't know how to validate '${ext}'`]
}
-
- // All is well. Nothing to complain about.
}
function checkSVGContent(content: string) {
@@ -148,10 +135,7 @@ function checkSVGContent(content: string) {
throw new Error(`contains a <${tagName}> tag`)
}
for (const key in 'attribs' in el ? el.attribs : {}) {
- // Looks for suspicious event handlers on tags.
- // For example `{rowParams.name}
- {/* This whitespace is important otherwise, when the CSS is
- ignored, the plain text becomes `foobar` if the HTML
- was `foobar`.
- */}{' '}
+ {/* Keeps foobar from rendering as foobar without CSS. */}{' '}
{Array.isArray(rowParams.type) ? rowParams.type.join(' or ') : rowParams.type}
- {/* Ditto about the important explicit whitespace */}{' '}
+ {/* Keeps readable text spacing if CSS fails to load. */}{' '}
{rowParams.isRequired ? (
{t('required')}
) : null}
@@ -75,7 +62,7 @@ export function ParameterRow({
{Array.isArray(rowParams.type) ? rowParams.type.join(' or ') : rowParams.type}
- {/* Ditto about the important explicit whitespace */}{' '}
+ {/* Keeps readable text spacing if CSS fails to load. */}{' '}
{rowParams.isRequired ? (
{t('required')}
) : null}
@@ -96,10 +83,7 @@ export function ParameterRow({
{t('default')}:
{typeof rowParams.default === 'string'
- ? // In the schema, the default value for strings can
- // potentially be the empty string so we handle this case
- // in particular by rendering it as "". Otherwise we would
- // display an empty code block which could be confusing.
+ ? // Empty string defaults need visible quotes.
rowParams.default || '""'
: JSON.stringify(rowParams.default)}
@@ -143,16 +127,7 @@ export function ParameterRow({
/>
)}
- {/* These conditions tell us:
-
- 1. the param is an object or array AND:
- 2. the param has no child param groups AND:
- 3. the param isn't one of the common webhook properties
-
- If all these are true, then that means we haven't yet loaded the
- nested parameters so we show a stub Heading
-// ... -// -// When this is the case, by default, that first.
-// Generally, the reason this even exists is because (and ) elements
-// are given extra margin-top so as to divide the article into sections
-// with some extra whitespace. That's fine, but we don't to start the
-// top of the page with too much whitespace. That's why @primer/css
-// has a solution for that. Just the problem that it fails then first
-// element isn't actually a heading.
-// Note we're also doing it for a possible being the first element.
+// Primer's markdown-body first-child reset can hit a hidden first child instead
+// of the first h2 or h3. Those headings carry section spacing, but the page top
+// must not start with it, so reset the first h2 or h3 directly.
// See https://github.com/primer/css/issues/2303
-// See internal issue #2368
.markdown-body {
> h2:first-of-type,
> h3:first-of-type {
@@ -23,9 +9,8 @@
}
}
-// Horizontal scroll gets flagged as an accessibility violation.
-// Updates all code examples to only allow vertical scroll, and
-// break aggressively.
+// Horizontal scroll gets flagged as an accessibility violation, so code examples wrap
+// aggressively and allow only vertical scrolling.
.markdown-body {
pre {
overflow-x: hidden;
@@ -38,97 +23,71 @@
}
}
-// Fix for permissions icon collision with bulleted lists
-// When permissions/product statements contain lists that start immediately,
-// the list bullets can visually collide with the icons in the flex layout.
-// This adds proper spacing to prevent the collision while supporting RTL languages
-// and avoiding effects on nested lists.
-// See: https://github.com/github/docs-engineering/issues/5199
+// Lists that start immediately in permissions and product statements can collide with
+// the icon in the flex layout. Inline spacing preserves right-to-left layouts and avoids
+// changing nested lists.
.permissions-statement,
.product-statement {
ul {
margin-inline-start: 0;
- padding-inline-start: 1rem; // Ensure proper spacing from icon (RTL-aware)
+ padding-inline-start: 1rem;
}
ul > li {
- margin-inline-start: 0.5rem; // Additional spacing to prevent bullet collision (direct children only)
+ margin-inline-start: 0.5rem;
}
}
-// A CTA button written on its own line in markdown — `` — becomes its own , and that paragraph already carries the 16px
-// rhythm margin. The `mt-3` utility then stacks a second 16px inside it, so the
-// button ends up 32px below the preceding line but only 16px above the next one.
-// Drop the utility when the button is alone in its paragraph and let the
-// paragraph margin do the spacing, which puts the CTA on the same rhythm as
-// every other block. `!important` is required because Primer's spacing
-// utilities are themselves !important.
-//
-// `:only-child` is doing real work here — it is what keeps the two cases apart:
-// - CTA callouts (`product:`/`permissions:` frontmatter) put the button after
-// a
INSIDE the prose paragraph, so there is no paragraph margin above
-// it and `mt-3` is the only thing separating it from the text.
-// - The side-by-side Yes/No `.btn-outline` pairs are two buttons in one
-// paragraph.
-// Neither is an only child, so both keep their margin.
+// A CTA button written alone in markdown, such as ,
+// becomes its own p. The p already has a 16px rhythm margin, and mt-3 adds another
+// 16px, leaving 32px below the preceding line but 16px above the next one.
+// Drop mt-3 only when the button is alone in its p; Primer spacing utilities use
+// !important too.
+// :only-child keeps CTA callouts and side-by-side Yes/No buttons unchanged. Frontmatter
+// product: and permissions: put the CTA after a br inside the prose p, so mt-3 supplies
+// its only top spacing. Yes/No .btn-outline pairs have two buttons in one p.
.markdown-body p > a.btn:only-child {
margin-top: 0 !important;
}
-// @primer/css holds `.btn` at `white-space: nowrap`, which a button cannot
-// honour and still stay inside a narrow column. The longest CTA label — "Set up
-// a trial of GitHub Enterprise Cloud", 322px — is wider than the article column
-// below a ~420px viewport and wider than the callout's text column below ~390px,
-// so the button ran past the content edge and was clipped.
+// @primer/css sets .btn to white-space: nowrap, which makes long CTA labels overflow
+// narrow columns. The longest CTA label, "Set up a trial of GitHub Enterprise Cloud",
+// measures 322px, wider than the article column below about 420px and the callout text
+// column below about 390px, so it gets clipped.
//
-// Letting the label wrap fixes it with no breakpoint to guess at. An
-// inline-block is shrink-to-fit — min(max-content, available) — so
-// `white-space: normal` changes nothing until max-content exceeds the space
-// available: at every width where the button already fits it still renders on
-// one line, byte-identical. That also makes it self-correcting for longer
-// translated labels and for the narrower column a callout gives the same button.
+// Let labels wrap instead of guessing a breakpoint. inline-block shrink-to-fit,
+// min(max-content, available), means white-space: normal changes nothing until
+// max-content exceeds the available space. Buttons that fit still render on one line,
+// and longer translations or narrower callout columns self-correct.
.markdown-body a.btn,
.permissions-statement a.btn,
.product-statement a.btn {
white-space: normal;
- // Wrapping alone orphaned the trailing octicon on a line of its own: the
- // space between the label and the icon is a valid break point, and the
- // label filled the first line exactly. Laying the button out as a flex row
- // instead lets the label wrap within itself and keeps the icon beside it,
- // vertically centred. At widths where nothing wraps the result is within a
- // pixel of the inline-block it replaces: same 17px left inset, same 21px
- // right inset, same 32px height, still one line. The `gap` below covers the
- // one thing that does change.
+ // Wrapping alone can orphan the trailing octicon because the label/icon space can break.
+ // inline-flex lets the label wrap inside itself and keeps the icon beside it, centered.
+ // When nothing wraps, this stays within a pixel of inline-block: 17px left inset,
+ // 21px right inset, 32px height, and one line. The gap below covers the one change.
display: inline-flex;
align-items: center;
- // Flex layout eats the one thing that was separating the label from the icon.
- // The markup is `Label {% octicon "link-external" %}`, and that
- // literal space does survive Liquid and the markdown pipeline as a real text
- // node — but a whitespace-only text node between two flex items is not itself
- // a flex item, so no box is generated for it and the label ends up touching
- // the icon. `gap` puts the space back.
+ // Flex removes the literal space between the label and icon. In
+ // Label {% octicon "link-external" %}, Liquid and markdown preserve the
+ // space as a text node, but a whitespace-only text node between flex items creates no
+ // box, so the label touches the icon.
//
- // 4px rather than the measured width of that space glyph, because a space is
- // font- and locale-dependent — it measures differently on two machines here —
- // while 4px is the value Primer itself already uses between a button's icon
- // and its label. The button ends up a fraction of a pixel wider than it was
- // rather than most of a space narrower, on a number the design system owns.
+ // Use 4px instead of the measured space width because the space changes by font and
+ // locale. Primer already uses 4px between a button icon and label, so this
+ // design-system value makes the button slightly wider rather than most of a space narrower.
//
- // Only the label/icon gap is restored. Primer's `.btn .octicon` also carries
- // `margin-right: 4px`, which assumes a LEADING icon and so lands outside the
- // trailing icon on these CTAs, giving them 21px of inset on the right against
- // 17px on the left. That asymmetry is what ships today, so it stays — zeroing
- // it would restyle every CTA on the site, which is a different change from
- // keeping a long label inside its column.
+ // Restore only the label/icon gap. Primer .btn .octicon also has margin-right: 4px
+ // for leading icons, which lands outside these trailing CTA icons and gives 21px right
+ // inset against 17px left. Keep that asymmetry; zeroing it would restyle every CTA.
gap: 4px;
- // The octicon is a flex item now, and flex items shrink before their container
- // overflows. Once the label wraps, the icon is the only thing left to give, so
- // the 16px glyph was rendering at 11px in a 240px callout column. It is a
- // fixed-size icon; the label is what should absorb a narrow column.
+ // The octicon is a flex item, and flex items shrink before their container overflows.
+ // Once the label wraps, the icon is the only thing left to shrink, so the 16px glyph
+ // rendered at 11px in a 240px callout column. Keep the icon fixed and let the label absorb width.
.octicon {
flex-shrink: 0;
}
diff --git a/src/content-render/stylesheets/octicon-table-optimization.scss b/src/content-render/stylesheets/octicon-table-optimization.scss
index 23d1f9af5728..777b9d30f538 100644
--- a/src/content-render/stylesheets/octicon-table-optimization.scss
+++ b/src/content-render/stylesheets/octicon-table-optimization.scss
@@ -1,5 +1,5 @@
-// Octicon table optimization for pages with hundreds of repeated icons
-// Uses CSS background images instead of inline SVGs to dramatically reduce HTML size
+// Pages with hundreds of repeated octicons use CSS background images instead of inline SVGs
+// to reduce HTML size.
$octicon-check-path: "M13.78 4.22a.75.75 0 0 1 0 1.06l-7.25 7.25a.75.75 0 0 1-1.06 0L2.22 9.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018L6 10.94l6.72-6.72a.75.75 0 0 1 1.06 0Z";
$octicon-x-path: "M3.72 3.72a.75.75 0 0 1 1.06 0L8 6.94l3.22-3.22a.749.749 0 0 1 1.275.326.749.749 0 0 1-.215.734L9.06 8l3.22 3.22a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L8 9.06l-3.22 3.22a.751.751 0 0 1-1.042-.018.751.751 0 0 1-.018-1.042L6.94 8 3.72 4.78a.75.75 0 0 1 0-1.06Z";
diff --git a/src/content-render/stylesheets/syntax-highlighting.scss b/src/content-render/stylesheets/syntax-highlighting.scss
index 30b9b9efa5ae..e7b679732af0 100644
--- a/src/content-render/stylesheets/syntax-highlighting.scss
+++ b/src/content-render/stylesheets/syntax-highlighting.scss
@@ -8,10 +8,9 @@ from https://unpkg.com/highlight.js@9.15.8/styles/github.css
.hljs {
display: block;
padding: 0.5em;
- // The block's BASE text colour — the tokens below are prettylights, which has
- // no Brand equivalent and stays on Primer deliberately, but this one is just
- // "default text" and was painting Primer's #e6edf3 inside a Brand-framed code
- // block. The `background` is inert here (markdown-overrides paints the `pre`).
+ // Use Brand's default text color for the block itself. The syntax tokens below stay
+ // on Primer prettylights because Brand has no equivalent. Inside .markdown-body, Primer
+ // paints the pre and makes pre code transparent, so this background is inert there.
color: var(--brand-color-text-default);
background: var(--color-canvas-subtle);
}
diff --git a/src/data-directory/lib/data-directory.ts b/src/data-directory/lib/data-directory.ts
index 05e7049d93a6..56da0f47a565 100644
--- a/src/data-directory/lib/data-directory.ts
+++ b/src/data-directory/lib/data-directory.ts
@@ -17,6 +17,9 @@ interface DataDirectoryResult {
[key: string]: unknown
}
+// dataDirectory uses setWith because lodash set creates arrays for numeric release-note paths.
+// Example: release-notes.enterprise-server.2-20.0 must stay an object path.
+// See https://lodash.com/docs#set.
export default function dataDirectory(
dir: string,
opts: DataDirectoryOptions = {},
@@ -38,7 +41,6 @@ export default function dataDirectory(
const data: DataDirectoryResult = {}
- // find YAML and Markdown files in the given directory, recursively
const filenames = walk(dir, { includeBasePath: true }).filter((filename: string) => {
if (mergedOpts.ignorePatterns.some((pattern) => pattern.test(filename))) return false
@@ -51,7 +53,6 @@ export default function dataDirectory(
])
for (const [filename, fileContent] of files) {
- // derive `foo.bar.baz` object key from `foo/bar/baz.yml` filename
const key = filenameToKey(path.relative(dir, filename))
const extension = path.extname(filename).toLowerCase()
@@ -60,11 +61,6 @@ export default function dataDirectory(
processedContent = mergedOpts.preprocess(fileContent)
}
- // Add this file's data to the global data object.
- // Note we want to use `setWith` instead of `set` so we can customize the type during path creation.
- // If we just use `set`, then e.g. `release-notes.enterprise-server.2-20.0` will be an Array but
- // `release-notes.enterprise-server.3-0.0` will be an Object.
- // See https://lodash.com/docs#set for an explanation.
switch (extension) {
case '.json':
setWith(data, key, JSON.parse(processedContent), Object)
@@ -74,9 +70,7 @@ export default function dataDirectory(
break
case '.md':
case '.markdown':
- // Use `matter` to drop frontmatter, since localized reusable Markdown files
- // can potentially have frontmatter, but we want to prevent the frontmatter
- // from being rendered.
+ // Localized reusable Markdown can have frontmatter; strip it so content rendering hides it.
setWith(data, key, matter(processedContent).content, Object)
break
}
diff --git a/src/data-directory/lib/data-schemas/ctas.ts b/src/data-directory/lib/data-schemas/ctas.ts
index 2f97602bed03..31c2c0238c80 100644
--- a/src/data-directory/lib/data-schemas/ctas.ts
+++ b/src/data-directory/lib/data-schemas/ctas.ts
@@ -1,13 +1,9 @@
-// This schema enforces the structure for CTA (Call-to-Action) URL parameters
-// Used to validate CTA tracking parameters in documentation links
-
export default {
type: 'object',
additionalProperties: false,
required: ['ref_product', 'ref_type', 'ref_style'],
properties: {
- // GitHub Product: The GitHub product the CTA leads users to
- // Format: ref_product=copilot
+ // Example query parameter: ref_product=copilot.
ref_product: {
type: 'string',
name: 'Product',
@@ -26,8 +22,7 @@ export default {
],
},
- // Type of CTA: The type of action the CTA encourages users to take
- // Format: ref_type=trial
+ // Example query parameter: ref_type=trial.
ref_type: {
type: 'string',
name: 'Type',
@@ -35,8 +30,7 @@ export default {
enum: ['trial', 'purchase', 'engagement'],
},
- // CTA style: The way we are formatting the CTA in the docs
- // Format: ref_style=button
+ // Example query parameter: ref_style=button.
ref_style: {
type: 'string',
name: 'Style',
@@ -44,8 +38,7 @@ export default {
enum: ['button', 'text'],
},
- // Type of plan (Optional): For links to sign up for or trial a plan, the specific plan we link to
- // Format: ref_plan=business
+ // Example query parameter: ref_plan=business.
ref_plan: {
type: 'string',
name: 'Plan',
diff --git a/src/data-directory/lib/data-schemas/features.ts b/src/data-directory/lib/data-schemas/features.ts
index 1b9aa310350b..de81e35ff109 100644
--- a/src/data-directory/lib/data-schemas/features.ts
+++ b/src/data-directory/lib/data-schemas/features.ts
@@ -15,7 +15,6 @@ interface FeatureVersionsSchema {
additionalProperties: false
}
-// Copy the properties from the frontmatter schema.
const featureVersions: FeatureVersionsSchema = {
type: 'object',
properties: {
@@ -24,8 +23,7 @@ const featureVersions: FeatureVersionsSchema = {
additionalProperties: false,
}
-// Remove the feature versions properties.
-// We don't want to allow features within features! We just want pure versioning.
+// Each data/features file allows version gates but not nested feature gates.
delete (featureVersions.properties.versions.properties as Record | undefined)
?.feature
diff --git a/src/data-directory/lib/data-schemas/glossaries-candidates.ts b/src/data-directory/lib/data-schemas/glossaries-candidates.ts
index cfe6393c32a6..ae86460d98ac 100644
--- a/src/data-directory/lib/data-schemas/glossaries-candidates.ts
+++ b/src/data-directory/lib/data-schemas/glossaries-candidates.ts
@@ -7,7 +7,8 @@ export interface TermSchema {
export const term: TermSchema = {
type: 'string',
minLength: 1,
- pattern: '^((?!\\*).)*$', // no asterisks allowed
+ // Reject asterisks in glossary terms.
+ pattern: '^((?!\\*).)*$',
}
export interface GlossaryCandidateItem {
diff --git a/src/data-directory/lib/data-schemas/index.ts b/src/data-directory/lib/data-schemas/index.ts
index bd157c2afb63..9a082301823a 100644
--- a/src/data-directory/lib/data-schemas/index.ts
+++ b/src/data-directory/lib/data-schemas/index.ts
@@ -12,16 +12,14 @@ function resolveSchemaPath(filename: string): string {
const isTest = process.env.NODE_ENV === 'test'
if (isTest) {
- // Use relative paths that work for vitest and 4.x compatibility with
- // dynamic imports in particular
+ // Vitest dynamic imports need relative schema paths.
return `../lib/data-schemas/${filename}`
} else {
- // Use absolute paths that work for content linter and other contexts
+ // Content linter and other runtime contexts need absolute schema paths.
return `@/data-directory/lib/data-schemas/${filename}`
}
}
-// Auto-discover table schemas from data/tables/ directory
function loadTableSchemas(): DataSchemas {
const tablesDir = path.join(process.cwd(), 'data/tables')
const schemasDir = path.join(__dirname, 'tables')
@@ -43,7 +41,6 @@ function loadTableSchemas(): DataSchemas {
return tableSchemas
}
-// Manual schema registrations for non-table data
const manualSchemas: DataSchemas = {
'data/features': resolveSchemaPath('features.ts'),
'data/variables': resolveSchemaPath('variables.ts'),
@@ -51,9 +48,8 @@ const manualSchemas: DataSchemas = {
'data/code-languages.yml': resolveSchemaPath('code-languages.ts'),
'data/glossaries/candidates.yml': resolveSchemaPath('glossaries-candidates.ts'),
'data/glossaries/external.yml': resolveSchemaPath('glossaries-external.ts'),
- // Tables in subdirectories of data/tables are not picked up by loadTableSchemas(),
- // which only reads the top level, so the matrix is registered explicitly here.
- // The matrix/ entry is a directory schema: every per-IDE file is validated against it.
+ // Register the matrix directory schema because loadTableSchemas reads only top-level files.
+ // The directory schema validates every per-IDE file.
'data/tables/copilot/matrix': resolveSchemaPath('tables/copilot/matrix-ide.ts'),
'data/tables/copilot/matrix-meta.yml': resolveSchemaPath('tables/copilot/matrix-meta.ts'),
}
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/auto-model-selection.ts b/src/data-directory/lib/data-schemas/tables/copilot/auto-model-selection.ts
index 9b6ff927dd95..63b81d4f8cec 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/auto-model-selection.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/auto-model-selection.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in auto-model-selection.yml
-
const autoModelSelectionSchema = {
type: 'array',
items: {
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/matrix-ide.ts b/src/data-directory/lib/data-schemas/tables/copilot/matrix-ide.ts
index e91ddcc37c4c..e2b85f6cdc9b 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/matrix-ide.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/matrix-ide.ts
@@ -1,28 +1,15 @@
-// Schema for the per-IDE files in data/tables/copilot/matrix/
-//
-// Registered as a directory schema in src/data-directory/lib/data-schemas/index.ts,
-// so every file added to that directory is validated against this shape.
+// The directory schema registration validates every data/tables/copilot/matrix/.yml file.
-// Deliberately not an enum. The vocabulary is defined once, as data, in
-// matrix-meta.yml, and is enforced against every IDE file by the
-// 'every support level used is defined in matrix-meta' invariant in
-// src/data-directory/tests/copilot-matrix.ts. Repeating the values here would
-// be a fourth copy that can drift from the data — which is exactly what the
-// schema this file replaces did: it was missing 'closing-down'.
+// supportLevel stays open because matrix-meta.yml owns the vocabulary and tests enforce it.
+// Repeating values here would create a fourth copy that can drift from data.
const supportLevel = {
type: 'string',
}
-// Every version tracked here is 3-part, and that follows from what is tracked
-// rather than from convention: four of the six files track the Copilot
-// extension (marketplace versions are required to be x.y.z) and the two that
-// track the IDE itself, VS Code and Visual Studio, version that way natively.
-// Kept strict on purpose. It catches a dropped or added segment — the mistake
-// an updater reading release notes is most likely to make, and one the
-// cross-file invariants cannot see, since they only check that a version is
-// used consistently, not that it is real. If an IDE genuinely changes
-// versioning scheme, that is a deliberate decision: change this pattern and say
-// why in the PR.
+// All six matrix files use three-part versions: four track Copilot extension marketplace versions,
+// and VS Code and Visual Studio use three-part IDE versions natively.
+// Keep the pattern strict because cross-file tests catch consistency, not malformed versions.
+// Update this pattern if an IDE adopts a different version format.
const VERSION_PATTERN = '^\\d+\\.\\d+\\.\\d+$'
const copilotMatrixIdeSchema = {
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/matrix-meta.ts b/src/data-directory/lib/data-schemas/tables/copilot/matrix-meta.ts
index 8853dc696125..873642ba58e8 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/matrix-meta.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/matrix-meta.ts
@@ -1,7 +1,5 @@
-// Schema for data/tables/copilot/matrix-meta.yml
-//
-// Shared configuration for the Copilot IDE feature matrix. Per-IDE data lives in
-// data/tables/copilot/matrix/.yml and is validated by matrix-ide.ts.
+// matrix-meta.yml owns shared Copilot IDE matrix configuration.
+// Per-IDE data lives in data/tables/copilot/matrix/.yml and matrix-ide.ts validates it.
const copilotMatrixMetaSchema = {
type: 'object',
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/model-comparison.ts b/src/data-directory/lib/data-schemas/tables/copilot/model-comparison.ts
index 022eb8da25aa..6189c00e9ff6 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/model-comparison.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/model-comparison.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in model-comparison.yml
-
const modelComparisonSchema = {
type: 'object',
additionalProperties: false,
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/model-deprecation-history.ts b/src/data-directory/lib/data-schemas/tables/copilot/model-deprecation-history.ts
index ba31dc99efb6..84fc98abac18 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/model-deprecation-history.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/model-deprecation-history.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in model-deprecation-history.yml
-
const modelDeprecationHistorySchema = {
type: 'object',
additionalProperties: false,
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/model-release-status.ts b/src/data-directory/lib/data-schemas/tables/copilot/model-release-status.ts
index a00352c7735a..6918f92a8903 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/model-release-status.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/model-release-status.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in model-release-status.yml
-
const modelsReleaseStatusSchema = {
type: 'object',
additionalProperties: false,
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/model-supported-clients.ts b/src/data-directory/lib/data-schemas/tables/copilot/model-supported-clients.ts
index ffb28af36dc2..84475d8305aa 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/model-supported-clients.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/model-supported-clients.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in model-supported-clients.yml
-
const modelsSupportedClientsSchema = {
type: 'object',
additionalProperties: false,
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/model-supported-plans.ts b/src/data-directory/lib/data-schemas/tables/copilot/model-supported-plans.ts
index 401b46254091..1476e55a4774 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/model-supported-plans.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/model-supported-plans.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in model-supported-plans.yml
-
const modelSupportedPlansSchema = {
type: 'object',
additionalProperties: false,
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/models-and-pricing.ts b/src/data-directory/lib/data-schemas/tables/copilot/models-and-pricing.ts
index 96f8127cd22e..992153a91100 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/models-and-pricing.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/models-and-pricing.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in models-and-pricing.yml
-
const modelsAndPricingSchema = {
type: 'object',
additionalProperties: false,
diff --git a/src/data-directory/lib/data-schemas/tables/repository-roles.ts b/src/data-directory/lib/data-schemas/tables/repository-roles.ts
index 6774b9739d4b..ab0a2af84e5c 100644
--- a/src/data-directory/lib/data-schemas/tables/repository-roles.ts
+++ b/src/data-directory/lib/data-schemas/tables/repository-roles.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in data/tables/repository-roles.yml
-
const row = {
type: 'object',
additionalProperties: false,
@@ -9,13 +7,11 @@ const row = {
type: 'string',
lintable: true,
},
- // Liquid that renders non-empty when the row should be shown. When omitted,
- // the row is shown on every version.
+ // Non-empty Liquid output limits the row to matching versions; omitting it renders everywhere.
versions: {
type: 'string',
},
- // Comma separated list of the roles that can perform the action. Roles left
- // out render as no. May contain Liquid, so a single role can be conditional.
+ // Comma-separated roles can contain Liquid; omitted roles render as no.
roles: {
type: 'string',
},
diff --git a/src/data-directory/lib/data-schemas/tables/rest-api-versions.ts b/src/data-directory/lib/data-schemas/tables/rest-api-versions.ts
index 046c02afe403..b0e5aef2741d 100644
--- a/src/data-directory/lib/data-schemas/tables/rest-api-versions.ts
+++ b/src/data-directory/lib/data-schemas/tables/rest-api-versions.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in data/tables/rest-api-versions.yml
-
export default {
type: 'object',
additionalProperties: false,
diff --git a/src/data-directory/lib/data-schemas/tables/supported-code-languages.ts b/src/data-directory/lib/data-schemas/tables/supported-code-languages.ts
index a298f709ef15..a7836014e0d5 100644
--- a/src/data-directory/lib/data-schemas/tables/supported-code-languages.ts
+++ b/src/data-directory/lib/data-schemas/tables/supported-code-languages.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in data/tables/supported-code-languages.yml
-
export default {
type: 'object',
additionalProperties: false,
@@ -164,7 +162,7 @@ export default {
type: 'object',
additionalProperties: false,
patternProperties: {
- // Language names like C, C++, C#, Go, Java, JavaScript, etc.
+ // Matches language names like C, C++, C#, Go, Java, and JavaScript.
'^[a-zA-Z+#]+$': {
type: 'object',
additionalProperties: false,
@@ -188,15 +186,15 @@ export default {
},
codeScanning: {
type: 'string',
- // Allow "supported", "not-supported", or custom text like "third-party [^1]"
+ // Accepts supported, not-supported, or custom text such as "third-party [^1]".
},
depGraph: {
type: 'string',
- // Allow "supported", "not-supported", or specific package managers like "npm, Yarn"
+ // Accepts supported, not-supported, or package managers such as "npm, Yarn".
},
depUpdates: {
type: 'string',
- // Allow "supported", "not-supported", or specific package managers
+ // Accepts supported, not-supported, or package managers.
},
actions: {
type: 'string',
@@ -204,7 +202,7 @@ export default {
},
packages: {
type: 'string',
- // Allow "supported", "not-supported", or specific package managers
+ // Accepts supported, not-supported, or package managers.
},
},
},
diff --git a/src/data-directory/lib/filename-to-key.ts b/src/data-directory/lib/filename-to-key.ts
index e46c27903709..b9eaf51fbaf7 100644
--- a/src/data-directory/lib/filename-to-key.ts
+++ b/src/data-directory/lib/filename-to-key.ts
@@ -3,14 +3,12 @@ import path from 'path'
const leadingPathSeparator = new RegExp(`^${RegExp.escape(path.sep)}`)
const windowsLeadingPathSeparator = new RegExp('^/')
-// all slashes in the filename. path.sep is OS agnostic (windows, mac, etc)
+// path.sep handles the current OS; the slash and backslash regexes handle paths from other systems.
const pathSeparator = new RegExp(RegExp.escape(path.sep), 'g')
const windowsPathSeparator = new RegExp('/', 'g')
-// handle MS Windows style double-backslashed filenames
const windowsDoubleSlashSeparator = new RegExp('\\\\', 'g')
-// derive `foo.bar.baz` object key from `foo/bar/baz.yml` filename
export default function filenameToKey(filename: string): string {
const extension = new RegExp(`${RegExp.escape(path.extname(filename))}$`)
const key = filename
diff --git a/src/data-directory/lib/get-data.ts b/src/data-directory/lib/get-data.ts
index 65b3d8d8bc91..85f7acf1bd09 100644
--- a/src/data-directory/lib/get-data.ts
+++ b/src/data-directory/lib/get-data.ts
@@ -20,14 +20,10 @@ interface FileSystemError extends Error {
code?: string
}
-// If you run `export DEBUG_JIT_DATA_READS=true` in your terminal,
-// next time it will mention every file it reads from disk.
+// Set DEBUG_JIT_DATA_READS=true to log every data file read from disk.
const DEBUG_JIT_DATA_READS = Boolean(JSON.parse(process.env.DEBUG_JIT_DATA_READS || 'false'))
-// This is a list of files that we should always immediately fall back to
-// English for.
-// Having this is safer than trying to wrangle the translations to NOT
-// have them translated.
+// Product and Copilot paths belong in the English-only set; translations can change fixed names.
const ALWAYS_ENGLISH_YAML_FILES = new Set([
'data/variables/product.yml',
'data/variables/copilot.yml',
@@ -37,17 +33,13 @@ const ALWAYS_ENGLISH_MD_FILES = new Set([
'data/reusables/ssh/known_hosts.md',
])
-// Returns all the things inside a directory
export const getDeepDataByLanguage = memoize(
(dottedPath: string, langCode: string, dir: string | null = null): Record => {
if (!(langCode in languages)) {
throw new Error(`langCode '${langCode}' not a recognized language code`)
}
- // The `dir` argument is only used for testing purposes.
- // For example, our unit tests that depend on using a fixtures root.
- // If we don't allow those tests to override the `dir` argument,
- // it'll be stuck from the first time `languages.ts` was imported.
+ // Tests pass a fixture root because languages-server.ts captures directories when it loads.
if (dir === null) {
dir = languages[langCode].dir
}
@@ -55,8 +47,7 @@ export const getDeepDataByLanguage = memoize(
},
)
-// Doesn't need to be memoized because it's used by getDataKeysByLanguage
-// which is already memoized.
+// getDeepDataByLanguage caches each top-level path, so recursive reads need no extra cache.
function getDeepDataByDir(dottedPath: string, dir: string): Record {
const fullPath = ['data']
const split = dottedPath.split(/\./g)
@@ -66,7 +57,8 @@ function getDeepDataByDir(dottedPath: string, dir: string): Record {
const uiEnglish = getUIData('en')
if (langCode === 'en') return uiEnglish as UIStrings
- // Got to combine. Start with the English and put the translation on top.
- // E.g.
- // english = {food: "Food", drink: "Drink"}
- // swedish = {food: "Mat"}
- // =>
- // combind = {food: "Mat", drink: "Drink"}
+ // Merge translations over English so missing localized UI keys fall back to English.
const combined: Record = {}
merge(combined, uiEnglish)
merge(combined, getUIData(langCode))
return combined as UIStrings
})
-// Doesn't need to be memoized because it's used by another function
-// that is memoized.
+// getUIDataMerged memoizes results, so this reader needs no separate cache.
const getUIData = (langCode: string): Record => {
const fullPath = ['data', 'ui.yml']
const { dir } = languages[langCode]
return getYamlContent(dir, fullPath.join(path.sep)) as Record
}
+// When translated data misses a dotted path, retry English.
+// lodash get returns undefined for the missing dotted path instead of ENOENT.
export const getDataByLanguage = memoize((dottedPath: string, langCode: string): unknown => {
if (!(langCode in languages))
throw new Error(`langCode '${langCode}' not a recognized language code`)
@@ -116,32 +104,20 @@ export const getDataByLanguage = memoize((dottedPath: string, langCode: string):
try {
const value = getDataByDir(dottedPath, dir, languages.en.dir, langCode)
- // What could happens is that a new key has only been added to
- // the English data/ui.yml but hasn't been added to Japanese, but
- // there nevertheless exists a Japanese `data/ui.yml`.
- // Since getDataByDir() uses `get(dataObject, 'dott.ed.path')` it
- // will return `undefined` if it's not present.
- // If this happens, we can't rely on `err.code === 'ENOENT'` to
- // fall back the English one. So we just start over using the English data.
if (value === undefined && langCode !== 'en') {
return getDataByDir(dottedPath, languages.en.dir)
}
return value
} catch (error) {
if (error instanceof Error && (error as YAMLException).mark && error.message) {
- // It's a load() generated error!
- // Remember, the file that we read might have been a .yml or a .md
- // file. If it was a .md file, with corrupt front-matter that too
- // would have caused a YAMLException
+ // Corrupt YAML files and Markdown frontmatter raise YAMLException, so translations fall back.
if (langCode !== 'en') {
if (DEBUG_JIT_DATA_READS) {
logger.warn('Unable to parse Yaml in translation', { langCode, dottedPath, error })
}
- // Give it one more chance, but use English this time
return getDataByDir(dottedPath, languages.en.dir)
}
- // Always throw English Yaml reading errors. Staff writers
- // need to know early and explicitly that they are corrupt.
+ // Throw English YAML errors so staff writers see corrupt source data early.
throw error
}
@@ -150,6 +126,10 @@ export const getDataByLanguage = memoize((dottedPath: string, langCode: string):
}
})
+// getSmartSplit preserves dotted path segments such as version-3.4.
+// Release notes split normally because numeric paths such as 3-7/0.yml would combine incorrectly.
+// getDataByDir keeps {% data early-access.reusables.foo.bar %} under data/early-access.
+// That data lives at data/early-access/reusables/foo/bar.md.
function getDataByDir(
dottedPath: string,
dir: string,
@@ -158,28 +138,10 @@ function getDataByDir(
): unknown {
const fullPath = ['data']
- // Using English here because it doesn't matter. We just want to
- // figure out how to turn `foo.version-3.4.deeper.key' into
- // `['foo', 'version-3.4', 'deeper', 'key']` here and we'll need
- // any directory to do that and English is always the most up-to-date.
- // We need the getSmartSplit() as long as there's a chance that a
- // directory or file inside data/ might contain a dot in the name,
- // however the exception is the file names in data/release-notes/**/*.yml
- // because it contains files that are just numbers like 3-7/0.yml and
- // that can cause problems inside getSmartSplit().
const split = dottedPath.startsWith('release-notes')
? dottedPath.split('.')
: getSmartSplit(dottedPath)
- // For early-access data stuff, they're referred to as...
- //
- // {% data early-access.reusables.foo.bar %}
- //
- // When we "merge" in the early-access data, we put the whole directory
- // within the root `data/` so it exists, on disk, as
- //
- // data/early-access/reusables/foo/bar.md
- //
if (split[0] === 'early-access') {
fullPath.push(split.shift()!)
}
@@ -233,24 +195,12 @@ function getDataByDir(
const markdown = getMarkdownContent(dir, fullPath.join(path.sep), englishRoot)
let { content } = matter(markdown)
if (dir !== englishRoot) {
- // If we're reading a translation, we need to replace the possible
- // corruptions. For example `[AUTOTITLE"을](/foo/bar)`.
- // To do this we'll need the English equivalent
+ // Translated reusables need English content to fix corruptions like [AUTOTITLE"을](/foo/bar).
let englishContent = content
try {
englishContent = getMarkdownContent(englishRoot, fullPath.join(path.sep), englishRoot)
} catch (error) {
- // In some real but rare cases a reusable doesn't exist in English.
- // At all.
- // This can happen when the translation is really out of date.
- // You might have an old `docs-internal.locale/content/**/*.md`
- // file that mentions `{% data reusables.foo.bar %}`. And it's
- // working fine, except none of that exists in English.
- // If this is the case, we still want to executed the
- // correctTranslatedContentStrings() function, but we can't
- // genuinely give it the English equivalent content, which it
- // sometimes uses to correct some Liquid tags. At least other
- // good corrections might happen.
+ // Translated pages can reference reusables missing in English; other corrections still run.
if ((error as FileSystemError).code !== 'ENOENT') {
throw error
}
@@ -263,9 +213,9 @@ function getDataByDir(
return content
}
- // E.g. {% data ui.pages.foo.bar %}
+ // UI data references such as {% data ui.pages.foo.bar %} read from data/ui.yml.
if (first === 'ui') {
- const basename = split.shift() // i.e. 'ui'
+ const basename = split.shift()
fullPath.push(`${basename}.yml`)
const allData = getYamlContent(dir, fullPath.join(path.sep), englishRoot)
return get(allData, split.join('.'))
@@ -292,7 +242,7 @@ function getSmartSplit(dottedPath: string): string[] {
const next = split[i + 1]
if (/\d$/.test(bit) && /^\d/.test(next)) {
bits.push([bit, next].join('.'))
- i++ // jump ahead one position in the loop
+ i++
} else {
bits.push(bit)
}
@@ -301,36 +251,12 @@ function getSmartSplit(dottedPath: string): string[] {
return bits
}
-// The reason this is memoized, even though the parent caller function
-// (`getDataByLanguage`) is also memoized is because we might read
-// the same file for two different keys. E.g.
-//
-// getDataByLanguage('variables.product.prodname_ghe_server', 'en')
-// getDataByLanguage('variables.product.company_short', 'en')
-//
-// ...will actually depend on reading `data/variables/product.yml`. Twice.
-// Well, actually not twice because we cache the disk reading. So the outcome
-// becomes this:
-//
-// 1. getDataByLanguage('variables.product.prodname_ghe_server', 'en')
-// -> cache MISS
-// 1.1. read and parse data/variables/product.yml
-// -> cache MISS
-// 2. getDataByLanguage('variables.product.company_short', 'en')
-// -> cache MISS
-// 2.1. read and parse data/variables/product.yml
-// -> cache HIT (Yay!)
-//
+// getDataByLanguage caches each dotted key, but different keys can read the same YAML file.
+// Cache YAML reads too, so product name variables share data/variables/product.yml.
const getYamlContent = memoize(
(root: string | undefined, relPath: string, englishRoot?: string): unknown => {
- // Certain Yaml files we know we always want the English one
- // no matter what the specified language is.
- // For example, we never want `data/variables/product.yml` translated
- // so we know to immediately fall back to the English one.
if (ALWAYS_ENGLISH_YAML_FILES.has(relPath)) {
- // This forces it to read from English. Later, when it goes
- // into `getFileContent(...)` it will note that `root !== englishRoot`
- // so it won't try to fall back.
+ // Passing englishRoot prevents getFileContent from treating this as a translation fallback.
root = englishRoot
}
const fileContent = getFileContent(root, relPath, englishRoot)
@@ -338,13 +264,10 @@ const getYamlContent = memoize(
},
)
-// The reason why this is memoized, is the same as for getYamlContent() above.
+// Cache Markdown reads too because different dotted keys can hit the same file.
const getMarkdownContent = memoize(
(root: string | undefined, relPath: string, englishRoot?: string): string => {
- // Certain reusables we never want to be pulled from the translations.
- // For example, certain reusables don't contain any English prose. Just
- // facts like numbers or hardcoded key words.
- // If this is the case, forcibly always draw from the English files.
+ // SSH fingerprints and known_hosts contain facts, not prose, so they are meant to use English.
if (ALWAYS_ENGLISH_MD_FILES.has(relPath)) {
root = englishRoot
}
@@ -364,13 +287,9 @@ const getFileContent = (
try {
return fs.readFileSync(filePath, 'utf-8')
} catch (err) {
- // It might fail because that particular data entry doesn't yet
- // exist in a translation
if ((err as FileSystemError).code === 'ENOENT') {
- // If looking it up as a file fails, give it one more chance if the
- // read was for a translation.
if (englishRoot && root !== englishRoot) {
- // We can try again but this time using the English files
+ // Missing translated data falls back to English when an English root is available.
return getFileContent(englishRoot, relPath, englishRoot)
}
}
@@ -378,24 +297,15 @@ const getFileContent = (
}
}
+// Development bypasses caching because repeated sync reads stay cheap enough for debugging.
+// A benchmark sampled 10 common data files across 100 runs, with about 80% YAML files.
+// Median sync reads took 0.5 ms per 10 files, or 2.1 ms per 10 files with YAML parsing.
function memoize(
func: (...args: Args) => Return,
): (...args: Args) => Return {
const cache = new Map()
return (...args: Args) => {
if (process.env.NODE_ENV === 'development') {
- // It is very possible that certain files, when caching is disabled,
- // are read multiple times in short succession. E.g. `product.yml`.
- // So how expensive is it to read these files excessively?
- // To answer that, we benchmarked it by sampling 10 files from the
- // most common files that are used from `data/`. In fact, we ran 100
- // runs of 10 *different* files. About 80% of them were `.yml` files.
- // As a median, it takes **0.5ms to read 10 files from disk**
- // all in a sync manner.
- // Since most files coming through here is `.yml` files (e.g.
- // product.yml and ui.yml) if you also do the `load()` of the
- // read content, that number becomes **2.1ms to read and parse 10 files**.
- // So in conclusion, not a lot of time.
return func(...args)
}
diff --git a/src/data-directory/middleware/data-tables.ts b/src/data-directory/middleware/data-tables.ts
index 8edf5262f938..bb3ed7c20a32 100644
--- a/src/data-directory/middleware/data-tables.ts
+++ b/src/data-directory/middleware/data-tables.ts
@@ -6,13 +6,12 @@ let tablesCache: Record | null = null
const getTables = () => {
if (!tablesCache) {
- // Keep product-name-heavy reference tables in English only for now
+ // Product-name-heavy reference tables stay in English to avoid localized product names.
tablesCache = getDeepDataByLanguage('tables', 'en')
}
return tablesCache
}
-// Loads the YAML files under data/tables/ into req.context.
export default async function dataTables(req: ExtendedRequest, res: Response, next: NextFunction) {
if (!req.context) throw new Error('request not contextualized')
diff --git a/src/data-directory/scripts/deleted-features-pr-comment.ts b/src/data-directory/scripts/deleted-features-pr-comment.ts
index a601190d9c16..a88cc4565b36 100644
--- a/src/data-directory/scripts/deleted-features-pr-comment.ts
+++ b/src/data-directory/scripts/deleted-features-pr-comment.ts
@@ -1,12 +1,6 @@
-/**
- * This script is supposed to be used in Actions. When it's run in Actions
- * there will be an env var called GITHUB_REPOSITORY. If it's not there,
- * you can use this script as a CLI tool. For example:
- *
- * export GITHUB_TOKEN=github_pat_blablabla
- * npm run deleted-features-pr-comment -- github docs-internal main 2ba53b6a
- *
- */
+// Produces deleted-feature Markdown as an Actions output; without GITHUB_REPOSITORY, prints it.
+// Required: GITHUB_TOKEN.
+// CLI: npm run deleted-features-pr-comment -- github docs-internal main 2ba53b6a
import { context as github_context, getOctokit } from '@actions/github'
import { setOutput } from '@actions/core'
@@ -44,7 +38,6 @@ async function main(owner: string, repo: string, baseSHA: string, headSHA: strin
throw new Error(`GITHUB_TOKEN environment variable not set`)
}
const octokit = getOctokit(GITHUB_TOKEN)
- // get the list of file changes from the PR
const response = await octokit.rest.repos.compareCommitsWithBasehead({
owner,
repo,
@@ -62,10 +55,10 @@ async function main(owner: string, repo: string, baseSHA: string, headSHA: strin
console.warn(`Feature involved in this PR: ${filename}; Status: ${status}`)
if (status === 'removed') {
- // Bad
+ // Deleted feature files can stay referenced in translated content.
oldFilenames.push(filename)
} else if (status === 'renamed') {
- // Also bad
+ // Renamed feature files can stay referenced by the old name in translated content.
const previousFilename = file.previous_filename
oldFilenames.push(previousFilename)
} else {
diff --git a/src/data-directory/scripts/find-orphaned-features/find.ts b/src/data-directory/scripts/find-orphaned-features/find.ts
index 2398738b896c..43f7b73afde0 100644
--- a/src/data-directory/scripts/find-orphaned-features/find.ts
+++ b/src/data-directory/scripts/find-orphaned-features/find.ts
@@ -1,31 +1,8 @@
-/**
- * This script will loop over all pages, in all languages, and look at
- * the following:
- *
- * 1. `title` in frontmatter
- * 2. `intro` in frontmatter
- * 3. `shortTitle` in frontmatter (if present)
- * 4. the markdown body itself
- * 5. The `versions:` frontmatter key (if the page is in English)
- *
- * Then it will search out the features mentioned based on `data/features/*.yml`
- * It will make a Set of these (e.g. `dependabot-grouped-dependencies` and
- * `ghas-enablement-webhook`) and one by one pluck them away.
- *
- * After the pages, it will loop over the reusables in English, and do the
- * same search there. Once it's done the English, it loops over the
- * reusables in the translations (if they exist) and does the same search.
- *
- * Lastly, it will output the remaining features, as relative file paths.
- * For example, `data/features/havent-been-used-in-years.yml` so now you
- * know that file can be deleted.
- *
- * NOTE: A lot of translations have corrupted Liquid. So if we can't parse
- * the Liquid we fall back to string search. A regex will try to find
- * all `{% ifversion ... %}` (and `elsif`) and search for any features
- * mentioned inside that as a string.
- *
- */
+// Finds data/features/*.yml entries that no page, reusable, or variable references.
+// It scans title, intro, shortTitle, body, and English versions frontmatter across all pages.
+// It also scans English reusables and variables, then matching translated reusables.
+// Outputs remaining features as paths such as data/features/havent-been-used-in-years.yml.
+// If translated Liquid cannot parse, regex searches feature names in ifversion and elsif tags.
import { strictEqual } from 'node:assert'
import fs from 'fs'
@@ -118,12 +95,12 @@ function formatDelta(t0: Date, t1: Date) {
return `${(ms / 1000).toFixed(1)} seconds`
}
+// searchAndRemove scans translated reusables only when English has the same relative path.
+// English content lets correctTranslatedContentStrings repair Liquid before feature matching.
function searchAndRemove(features: Set, pages: Page[], verbose = false) {
for (const page of pages) {
const content = page.markdown
- // We actually never bother looking at the `versions:` frontmatter
- // key in translations, so it doesn't matter if the translated
- // frontmatter might have `versions: some-old-feature`.
+ // Only English versions frontmatter can mark a feature used.
if (page.languageCode === 'en') {
for (const [key, value] of Object.entries(page.versions)) {
if (key === 'feature') {
@@ -144,19 +121,6 @@ function searchAndRemove(features: Set, pages: Page[], verbose = false)
checkString(combined, features, { page, verbose, languageCode: page.languageCode })
}
- // Reusables are a bit special, as they are shared between languages.
- // There'll always be a slight mismatch between files present on disk
- // in English vs. translations.
- // The translations never delete files, so there's often excess reusables
- // on disk in translations. And the English might be ahead, meaning a file
- // has been introduced in English but not yet translated.
- // The code below loops over the English reusables, and takes note of the
- // their relative paths and content. Then, we re-use the keys of that map
- // to know which files, in the translations, to check. And when we read
- // them in, we'll need the English equivalent content to be able to
- // use the correctTranslatedContentStrings function.
-
- // Check the English variable files.
for (const filePath of getVariableFiles(path.join(languages.en.dir, 'data', 'variables'))) {
const fileContent = fs.readFileSync(filePath, 'utf-8')
checkString(fileContent, features, { filePath, verbose, languageCode: 'en' })
@@ -170,7 +134,7 @@ function searchAndRemove(features: Set, pages: Page[], verbose = false)
englishReusables.set(relativePath, fileContent)
}
for (const language of Object.values(languages)) {
- if (language.code === 'en') continue // Already did that in the loop above
+ if (language.code === 'en') continue
for (const [relativePath, englishFileContent] of Array.from(englishReusables.entries())) {
const filePath = path.join(language.dir, relativePath)
@@ -192,10 +156,7 @@ function searchAndRemove(features: Set, pages: Page[], verbose = false)
})
} catch (error) {
if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
- // That a reusable does *not* exist in a translation is
- // perfectly expected. It means that English reusable was
- // most likely added recently and the translation hasn't been
- // translated yet.
+ // Missing translated reusables are expected when English has newer files.
continue
}
throw error
@@ -243,10 +204,7 @@ function checkString(
}: { page?: Page; filePath?: string; languageCode?: string; verbose?: boolean } = {},
) {
try {
- // The reason for the `noCache: true` is that we're going to be sending
- // a LOT of different strings in and the cache will fill up rapidly
- // when testing every possible string in every possible language for
- // every page.
+ // Disable the Liquid token cache because scanning many different strings would fill it quickly.
const tokens = getLiquidTokens(string, { noCache: true }).filter(
(token): token is TagToken => token.kind === TokenKind.Tag,
)
@@ -264,11 +222,10 @@ function checkString(
}
} catch (error) {
if (error instanceof TokenizationError) {
- // If it happens in English, it's a serious error
+ // English Liquid parse failures are source errors.
if (languageCode === 'en') throw error
- // The translation might, currently, have corrupted liquid
- // So treat it as a string
+ // Translated Liquid can be corrupt, so regex search still catches feature references.
if (verbose)
console.log(
`TokenizationError in ${page ? page.fullPath : filePath}. Treating ${page ? page.fullPath : filePath} as a string and using regex`,
diff --git a/src/data-directory/scripts/find-orphaned-tables.ts b/src/data-directory/scripts/find-orphaned-tables.ts
index a254863b9b6a..9ce6e3e74898 100644
--- a/src/data-directory/scripts/find-orphaned-tables.ts
+++ b/src/data-directory/scripts/find-orphaned-tables.ts
@@ -1,20 +1,6 @@
-// [start-readme]
-//
-// Print a list of all the YAML-powered table files in ./data/tables/ that
-// can't be found mentioned in any source file (content, data & code), along
-// with their paired schema files. Mirrors find-orphaned-assets.ts.
-//
-// Tables are referenced from Liquid like:
-//
-// {% data tables.. %}
-// {% for entry in tables.. %}
-//
-// so a table file `data/tables//.yml` is "used" if the string
-// `tables..` appears anywhere. A deeper reference such as
-// `tables...` also counts, because the file key is a
-// prefix of it.
-//
-// [end-readme]
+// Prints unreferenced YAML-powered table files under ./data/tables/ and paired schema files.
+// Both {% data tables.copilot.matrix-meta %} and
+// {% for level in tables.copilot.matrix-meta.supportLevels %} mark the table used.
import fs from 'fs'
import path from 'path'
@@ -28,17 +14,15 @@ import languages from '@/languages/lib/languages-server'
const TABLES_DIR = 'data/tables'
const SCHEMAS_DIR = 'src/data-directory/lib/data-schemas/tables'
-// Tables that are referenced dynamically (not via Liquid) and must never be
-// flagged as orphans. Add an entry here (the dotted key, e.g. `copilot.foo`)
-// if a table is loaded by code rather than mentioned in content.
+// EXCEPTIONS protects tables loaded dynamically by code rather than mentioned in content.
const EXCEPTIONS = new Set([])
export type TableFile = {
- // Repo-relative path to the YAML file, e.g. data/tables/copilot/model-multipliers.yml
+ // Repo-relative YAML path, such as data/tables/copilot/model-multipliers.yml.
yml: string
// Repo-relative path to the paired schema, if it exists on disk.
schema?: string
- // Dotted key used in Liquid, e.g. copilot.model-multipliers
+ // Dotted Liquid key, such as copilot.model-multipliers.
key: string
}
@@ -72,9 +56,7 @@ type MainOptions = {
excludeTranslations: boolean
}
-// Given the table files and the contents of every source file, return the
-// tables whose Liquid key is never mentioned. Pulled out of main() so it can
-// be unit tested without touching the filesystem.
+// Exported for tests so orphan detection can run without filesystem reads.
export function getOrphanedTables(
tables: TableFile[],
sourceContents: Iterable,
@@ -91,8 +73,7 @@ export function getOrphanedTables(
return [...orphans.values()].sort((a, b) => a.yml.localeCompare(b.yml))
}
-// Only parse argv and run when invoked directly (e.g. via `npm run
-// find-orphaned-tables`), not when imported by a test.
+// Guard main so tests can import getOrphanedTables; npm run find-orphaned-tables invokes it.
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
program.parse(process.argv)
main(program.opts())
@@ -108,10 +89,7 @@ async function main(opts: MainOptions) {
const sourceFiles: string[] = [...englishFiles]
if (!excludeTranslations) {
- // Translations are often behind English. A table can still be referenced
- // in a translation even when no English content references it, so we must
- // search translations too. We only look at files that also exist in
- // English, because translations rarely delete renamed/removed files.
+ // Search matching translations because translated content can still reference a table.
const englishRelativeFiles = new Set(
englishFiles.map((englishFile) => path.relative(languages.en.dir, englishFile)),
)
@@ -133,9 +111,7 @@ async function main(opts: MainOptions) {
}
}
- // Tables can also be referenced from code (e.g. table-rendering helpers), so
- // search src and contributing as well. Searching more files only ever marks
- // a table as used, never as an orphan, so it errs on the safe side.
+ // Search code because table-rendering helpers can reference tables without Liquid.
for (const root of ['contributing', 'src']) {
if (!fs.existsSync(root)) continue
sourceFiles.push(
@@ -165,9 +141,7 @@ async function main(opts: MainOptions) {
const orphanTables = getOrphanedTables(tables, readContents())
- // Safety net: if every table looks orphaned, the detection is almost
- // certainly broken (e.g. content wasn't checked out). Refuse to suggest
- // deleting everything.
+ // If every table looks orphaned, detection is probably broken; refuse to list deletions.
if (tables.length > 0 && orphanTables.length === tables.length) {
console.error(
'Every table was flagged as orphaned, which is almost certainly a bug. ' +
diff --git a/src/data-directory/tests/copilot-matrix.ts b/src/data-directory/tests/copilot-matrix.ts
index d12ec6ae8f8e..529344ab9c43 100644
--- a/src/data-directory/tests/copilot-matrix.ts
+++ b/src/data-directory/tests/copilot-matrix.ts
@@ -4,23 +4,14 @@ import { join } from 'path'
import { load } from 'js-yaml'
import { describe, expect, test } from 'vitest'
-// Cross-file invariants for the Copilot IDE feature matrix.
-//
-// The JSON schemas validate each file in isolation. These tests cover the
-// relationships *between* matrix-meta.yml and the per-IDE files, which is where
-// a hand edit — or, later, an automated changelog-driven update — is most
-// likely to introduce a silent error.
-//
-// "Silent" is the operative word: a missing or mistyped key does not raise an
-// error, it renders as ✗ (not supported) to customers.
+// JSON schemas validate each file in isolation. These tests cover cross-file matrix relationships.
+// Missing or mistyped keys silently render as ✗ (not supported) in customer-facing tables.
const MATRIX_DIR = join(process.cwd(), 'data/tables/copilot/matrix')
const META_PATH = join(process.cwd(), 'data/tables/copilot/matrix-meta.yml')
-// Stands for "supported since before we tracked versions". Some IDEs list it in
-// `versions` without putting it in a `versionGroup`, so it is the one version
-// allowed to have no detail table. Removing it is a customer-visible content
-// decision; until then it is excluded from the grouping invariant below.
+// Some IDEs use 0.0.0 for supported-before-tracking without a versionGroup.
+// Removing the sentinel is customer-visible, so the grouping invariant excludes it.
const SENTINEL_VERSION = '0.0.0'
type Ide = {
@@ -70,8 +61,7 @@ describe('copilot matrix meta', () => {
expect(new Set(meta.featureOrder).size).toBe(meta.featureOrder.length)
})
- // A stale featureOrder entry that no IDE uses renders as a row of ✗ across
- // every column of the summary table.
+ // A stale featureOrder entry renders as a row of ✗ across every summary-table column.
test('every featureOrder entry is used by at least one IDE', () => {
const used = new Set()
for (const ide of Object.values(ides)) {
@@ -114,13 +104,9 @@ describe.each(ideFilenames)('copilot matrix: %s', (slug) => {
).toEqual([])
})
- // Only versions listed in a versionGroup are rendered as a detail table. A
- // version in `versions` that is in no group is data customers cannot see —
- // and the summary table reads `versions | first`, so if it is the newest one
- // the page shows support data for a version with no detail table at all.
- // This is the most likely mistake for an automated updater that appends to
- // `versions` and forgets `versionGroups`, and checking only the newest
- // version would miss a backfilled older one.
+ // Only versions listed in versionGroups render detail tables. The test skips the 0.0.0 sentinel.
+ // The summary table reads versions | first, so an ungrouped newest version has no detail table.
+ // Checking every version also catches backfilled older versions that automated updates miss.
test('every version appears in at least one versionGroup', () => {
const grouped = new Set(Object.values(ide.versionGroups).flat())
const ungrouped = ide.versions.filter(
diff --git a/src/data-directory/tests/data-schemas.ts b/src/data-directory/tests/data-schemas.ts
index 7dd168ade55b..bc2b83a61f37 100644
--- a/src/data-directory/tests/data-schemas.ts
+++ b/src/data-directory/tests/data-schemas.ts
@@ -64,7 +64,6 @@ describe('YAML-powered tables', () => {
const schemaPath = join(schemasDir, `${name}.ts`)
expect(existsSync(schemaPath)).toBe(true)
- // Also verify it's registered in the dataSchemas
const dataKey = `data/tables/${yamlFile}`
expect(dataSchemas[dataKey]).toBeDefined()
}
diff --git a/src/data-directory/tests/find-orphaned-tables.ts b/src/data-directory/tests/find-orphaned-tables.ts
index b3ac92a04978..1dfc47015020 100644
--- a/src/data-directory/tests/find-orphaned-tables.ts
+++ b/src/data-directory/tests/find-orphaned-tables.ts
@@ -41,8 +41,6 @@ describe('getOrphanedTables', () => {
})
test('counts a deeper sub-key reference as using the table file', () => {
- // A reference to `tables.copilot.copilot-matrix.ides` should mark the
- // `copilot.copilot-matrix` file as used.
const orphans = getOrphanedTables(
[table('copilot.copilot-matrix')],
['{% for row in tables.copilot.copilot-matrix.ides %}'],
@@ -51,8 +49,6 @@ describe('getOrphanedTables', () => {
})
test('does not let a longer key falsely mark a shorter, unrelated table', () => {
- // `tables.copilot.annual-subscriber-model-multipliers` must NOT mark
- // `copilot.model-multipliers` as used.
const orphans = getOrphanedTables(
[table('copilot.model-multipliers')],
['{% data tables.copilot.annual-subscriber-model-multipliers %}'],
diff --git a/src/data-directory/tests/get-data.ts b/src/data-directory/tests/get-data.ts
index 7b3a0414f929..68e834bce35e 100644
--- a/src/data-directory/tests/get-data.ts
+++ b/src/data-directory/tests/get-data.ts
@@ -14,7 +14,7 @@ import { DataDirectory } from '@/tests/helpers/data-directory'
describe('get-data', () => {
let dd: DataDirectory
const enDirBefore = languages.en.dir
- // Only `en` is available in tests, so pretend we also have Japanese
+ // Only en is available in tests, so copy English metadata for Japanese fixtures.
languages.ja = Object.assign({}, languages.en, {})
beforeAll(() => {
@@ -77,12 +77,10 @@ describe('get-data', () => {
const result = getDataByLanguage('variables.stuff.foo', 'en')
expect(result).toBe('Foo')
}
- // Test that memoization doesn't go wrong
{
const result = getDataByLanguage('variables.stuff.bar', 'en')
expect(result).toBe('Bar')
}
- // Test that unrecognized keys just return `undefined`
{
const result = getDataByLanguage('variables.stuff.neverheardof', 'en')
expect(result).toBeUndefined()
@@ -94,12 +92,10 @@ describe('get-data', () => {
const result = getDataByLanguage('variables.stuff.foo', 'ja')
expect(result).toBe('フー')
}
- // Test fallback to English if not present in translation
{
const result = getDataByLanguage('variables.stuff.bar', 'ja')
expect(result).toBe('Bar')
}
- // Test that unrecognized keys just return `undefined`
{
const result = getDataByLanguage('variables.stuff.neverheardof', 'ja')
expect(result).toBeUndefined()
@@ -111,12 +107,10 @@ describe('get-data', () => {
const result = getDataByLanguage('variables.stuff.key_non_existent', 'en')
expect(result).toBeUndefined()
}
- // Test fallback to English if not present in translation
{
const result = getDataByLanguage('variables.stuff.key_non_existent', 'ja')
expect(result).toBeUndefined()
}
- // Returns undefined if not only the key is missing but the whole file too
{
const result = getDataByLanguage('variables.notpresent.whatever', 'en')
expect(result).toBeUndefined()
@@ -128,7 +122,6 @@ describe('get-data', () => {
const result = getDataByLanguage('reusables.coolness', 'en')
expect(result).toBe('This is *Markdown*')
}
- // Test that memoization doesn't go wrong
{
const result = getDataByLanguage('reusables.otherness', 'en')
expect(result).toBe('**Also** Markdown')
@@ -140,7 +133,6 @@ describe('get-data', () => {
const result = getDataByLanguage('reusables.coolness', 'ja')
expect(result).toBe('これがマークダウンです')
}
- // Test translations fall back to English if file doesn't exist
{
const result = getDataByLanguage('reusables.otherness', 'ja')
expect(result).toBe('**Also** Markdown')
@@ -152,7 +144,6 @@ describe('get-data', () => {
const result = getDataByLanguage('reusables.neverheardof', 'en')
expect(result).toBeUndefined()
}
- // Test translations will try English but fail if the fallback fails too
{
const result = getDataByLanguage('reusables.neverheardof', 'ja')
expect(result).toBeUndefined()
@@ -165,12 +156,10 @@ describe('get-data', () => {
expect(result.key).toBe('Value')
expect((result.deep as Record).er).toBe('Depth')
}
- // In a specific language
{
const result = getUIDataMerged('ja')
expect(result.key).toBe('価値')
expect((result.deep as Record).er).toBe('深さ')
- // Note how it falls back to English on that key
expect((result.deep as Record).est).toBe('Deepest')
}
})
@@ -181,7 +170,6 @@ describe('get-data', () => {
expect((result.stuff as Record).foo).toBe('Foo')
expect((result.stuff as Record).bar).toBe('Bar')
}
- // All reusables
{
const result = getDeepDataByLanguage('reusables', 'en')
expect(result['coolness.md']).toBe('This is *Markdown*')
@@ -213,7 +201,7 @@ front: >'matter
describe('get-data on corrupt translations', () => {
let dd: DataDirectory
const enDirBefore = languages.en.dir
- // Only `en` is available in vitest tests, so pretend we also have Japanese
+ // Only en is available in tests, so copy English metadata for Japanese fixtures.
languages.ja = Object.assign({}, languages.en, {})
beforeAll(() => {
@@ -263,12 +251,10 @@ describe('get-data on corrupt translations', () => {
})
test('getDataByLanguage on a corrupt .yml file', () => {
- // First make sure it works in English
{
const result = getDataByLanguage('variables.everything.is', 'en')
expect(result).toBe('Awesome')
}
- // Japanese translations would fall back due to a corrupt Yaml file
{
const result = getDataByLanguage('variables.everything.is', 'ja')
expect(result).toBe('Awesome')
@@ -276,12 +262,10 @@ describe('get-data on corrupt translations', () => {
})
test('getDataByLanguage on a corrupt .md file', () => {
- // First make sure it works in English
{
const result = getDataByLanguage('reusables.cool', 'en')
expect(result).toBe('*English* /Markdown/')
}
- // Japanese translations would fall back due to a corrupt Yaml file
{
const result = getDataByLanguage('reusables.cool', 'ja')
expect(result).toBe('*English* /Markdown/')
@@ -317,11 +301,11 @@ describe('get-data applies corrections to translated variables', () => {
data: {
variables: {
myproduct: {
- // Corrupted: `data` translated to Japanese `データ`
+ // Translation corrupts the data keyword to データ.
name: '{% データ variables.myproduct.name %}',
},
phases: {
- // Not corrupted, so it should pass through unchanged
+ // Valid ifversion stays unchanged.
preview: '{% ifversion ghes < 3.16 %}ベータ{% else %}パブリックプレビュー{% endif %}',
},
},
@@ -337,12 +321,10 @@ describe('get-data applies corrections to translated variables', () => {
})
test('corrects corrupted Liquid keywords in translated variables', () => {
- // English variable is returned as-is
{
const result = getDataByLanguage('variables.myproduct.name', 'en')
expect(result).toBe('GitHub')
}
- // Japanese translation with corrupted `データ` → `data` gets corrected
{
const result = getDataByLanguage('variables.myproduct.name', 'ja')
expect(result).toBe('{% data variables.myproduct.name %}')
@@ -350,7 +332,6 @@ describe('get-data applies corrections to translated variables', () => {
})
test('leaves valid translated variables unchanged', () => {
- // Valid ifversion in translated variable should pass through
{
const result = getDataByLanguage('variables.phases.preview', 'ja')
expect(result).toBe(
diff --git a/src/data-directory/tests/index.ts b/src/data-directory/tests/index.ts
index cdef3164a438..03e0de1a292b 100644
--- a/src/data-directory/tests/index.ts
+++ b/src/data-directory/tests/index.ts
@@ -31,16 +31,14 @@ describe('data-directory', () => {
const extensions = ['.yml', 'markdown']
const data = dataDirectory(fixturesDir, { extensions })
expect('bar' in data).toBe(true)
- expect('foo' in data).toBe(false) // JSON file should be ignored
+ expect('foo' in data).toBe(false)
})
test('option: ignorePatterns', async () => {
const ignorePatterns: RegExp[] = []
- // README is ignored by default
expect('README' in dataDirectory(fixturesDir)).toBe(false)
- // README can be included by setting empty ignorePatterns array
expect('README' in dataDirectory(fixturesDir, { ignorePatterns })).toBe(true)
})
})
diff --git a/src/data-directory/tests/orphaned-features.ts b/src/data-directory/tests/orphaned-features.ts
index ea931b6b4f21..e63c7c1f8db7 100644
--- a/src/data-directory/tests/orphaned-features.ts
+++ b/src/data-directory/tests/orphaned-features.ts
@@ -49,7 +49,6 @@ describe('orphaned features detection', () => {
})
test('helper functions handle nested directories', () => {
- // Create a temporary nested structure to test
const tempDir = path.join(__dirname, 'temp-nested-test')
const nestedVariablesDir = path.join(tempDir, 'variables', 'nested')
const nestedReusablesDir = path.join(tempDir, 'reusables', 'nested')
@@ -78,7 +77,6 @@ describe('orphaned features detection', () => {
})
test('helper functions ignore non-target files', () => {
- // Create a temporary directory with mixed file types
const tempDir = path.join(__dirname, 'temp-mixed-files')
fs.mkdirSync(tempDir, { recursive: true })
@@ -90,12 +88,10 @@ describe('orphaned features detection', () => {
fs.writeFileSync(path.join(tempDir, 'README.md'), '# README')
try {
- // getVariableFiles should only find .yml files (excluding README.yml)
const variableFiles = getVariableFiles(tempDir)
expect(variableFiles).toHaveLength(1)
expect(variableFiles[0]).toMatch(/test\.yml$/)
- // getReusableFiles should only find .md files (excluding README.md)
const reusableFiles = getReusableFiles(tempDir)
expect(reusableFiles).toHaveLength(1)
expect(reusableFiles[0]).toMatch(/test\.md$/)
@@ -105,13 +101,9 @@ describe('orphaned features detection', () => {
})
test('verify fix addresses the original issue scenario', () => {
- // This test simulates the original issue where features were used only in variables
- // but not detected by the orphaned features script
-
const variablesDir = path.join(fixturesDir, 'data', 'variables')
const featuresDir = path.join(fixturesDir, 'data', 'features')
- // Verify our test setup has the scenario described in the issue
expect(fs.existsSync(path.join(featuresDir, 'used-in-variables.yml'))).toBe(true)
expect(fs.existsSync(path.join(featuresDir, 'truly-orphaned.yml'))).toBe(true)
@@ -121,8 +113,6 @@ describe('orphaned features detection', () => {
const variableFiles = getVariableFiles(variablesDir)
expect(variableFiles.length).toBeGreaterThan(0)
- // This proves that the fix would catch features used in variables files
- // because the orphaned features script now scans these files
const foundFeatureUsage = variableFiles.some((filePath) => {
const content = fs.readFileSync(filePath, 'utf-8')
return content.includes('used-in-variables')
@@ -132,8 +122,6 @@ describe('orphaned features detection', () => {
})
test('functions correctly identify different file types in same directory', () => {
- // Create a directory with both .yml and .md files to ensure each function
- // only picks up its target file types
const tempDir = path.join(__dirname, 'temp-mixed-target-files')
fs.mkdirSync(tempDir, { recursive: true })
@@ -148,7 +136,6 @@ describe('orphaned features detection', () => {
fs.writeFileSync(path.join(tempDir, 'other.txt'), 'other content')
try {
- // Each function should only find its target file type
const variableFiles = getVariableFiles(tempDir)
const reusableFiles = getReusableFiles(tempDir)
diff --git a/src/data-directory/tests/ui-yml-structure.ts b/src/data-directory/tests/ui-yml-structure.ts
index edc8cf7e789a..91803b1c281e 100644
--- a/src/data-directory/tests/ui-yml-structure.ts
+++ b/src/data-directory/tests/ui-yml-structure.ts
@@ -13,7 +13,7 @@ describe('data/ui.yml structure', () => {
const violations: string[] = []
for (let i = 0; i < lines.length; i++) {
- // A top-level key starts at column 0 with a word followed by ':'
+ // Top-level keys start at column 0 with a word followed by colon.
if (/^[a-z_]+:/.test(lines[i]) && i > 0) {
if (lines[i - 1].trim() !== '') {
violations.push(`Line ${i + 1}: "${lines[i]}" is not preceded by a blank line`)
diff --git a/src/deployments/production/build-scripts/clone-or-use-cached-repo.sh b/src/deployments/production/build-scripts/clone-or-use-cached-repo.sh
index a908885ab652..0dad817f3ff9 100644
--- a/src/deployments/production/build-scripts/clone-or-use-cached-repo.sh
+++ b/src/deployments/production/build-scripts/clone-or-use-cached-repo.sh
@@ -1,11 +1,7 @@
set -e
-# Reuses the repo cached by a previous Dockerfile build, or clones it fresh
-# and checks out the given branch/SHA.
-# Arguments:
-# $1 - Repository name (for directory naming)
-# $2 - Repository URL
-# $3 - Branch to clone
+# Reuses a cached repo or clones it, then checks out the requested branch.
+# Arguments: $1 cache directory, $2 GitHub repo name under github, $3 branch.
clone_or_use_cached_repo() {
repo_name="$1"
repo_url="$2"
diff --git a/src/deployments/production/build-scripts/fetch-repos.sh b/src/deployments/production/build-scripts/fetch-repos.sh
index 3f2239fc448e..9f24050f0013 100644
--- a/src/deployments/production/build-scripts/fetch-repos.sh
+++ b/src/deployments/production/build-scripts/fetch-repos.sh
@@ -1,7 +1,7 @@
#!/usr/bin/env sh
-# Called from the production Dockerfile. The Dockerfile only COPYs what it
-# needs, but these scripts still run as if from the docs-internal root.
+# The production Dockerfile copies only required files, but these scripts still run from the
+# docs-internal root.
echo "Fetching and resolving early-access, and translations repos"
@@ -9,7 +9,7 @@ set -e
. ./build-scripts/clone-or-use-cached-repo.sh
-# From the --secret mounted by the Docker build.
+# Docker build mounts DOCS_BOT_PAT_BASE at /run/secrets/DOCS_BOT_PAT_BASE.
GITHUB_TOKEN=$(cat /run/secrets/DOCS_BOT_PAT_BASE)
echo "Fetching early access..."
@@ -17,11 +17,11 @@ clone_or_use_cached_repo "docs-early-access" "docs-early-access" "main"
echo "Merging early access..."
. ./build-scripts/merge-early-access.sh
-# Clone into `translations/` inside the Dockerfile's WORKDIR, the docs-internal root.
+# Clone translations under the Dockerfile WORKDIR, the docs-internal root.
mkdir -p translations
cd translations
-# Temporarily turn off exit-on-error so we can collect all PIDs
+# Disable exit-on-error so the script can collect every background clone failure.
set +e
pids=""
@@ -35,7 +35,6 @@ for pid in $pids; do
wait "$pid" || failures=$((failures+1))
done
-# Restore strict mode
set -e
if [ "$failures" -gt 0 ]; then
@@ -45,8 +44,8 @@ else
echo "✅ All translations fetched."
fi
-# Go back to the root of the docs-internal repo
+# Return to the docs-internal root after cloning translations.
cd ..
-# Don't leave the token in the environment.
+# Remove the token from the shell environment.
unset GITHUB_TOKEN
diff --git a/src/deployments/production/build-scripts/merge-early-access.sh b/src/deployments/production/build-scripts/merge-early-access.sh
index 317f81a9dc87..00a3c3bfef7a 100755
--- a/src/deployments/production/build-scripts/merge-early-access.sh
+++ b/src/deployments/production/build-scripts/merge-early-access.sh
@@ -1,7 +1,6 @@
#!/usr/bin/env sh
-# Merges docs-early-access files into docs-internal. Runs from the
-# docs-internal root.
+# Merges docs-early-access files into docs-internal from the docs-internal root.
mv docs-early-access/assets/images assets/images/early-access
mv docs-early-access/content content/early-access
diff --git a/src/dev-toc/generate.ts b/src/dev-toc/generate.ts
index f883ccbbad96..3d7c16ffc1ec 100644
--- a/src/dev-toc/generate.ts
+++ b/src/dev-toc/generate.ts
@@ -1,14 +1,10 @@
-/**
- * @purpose Writer tool
- * @description Generate a local table of contents for the GitHub Docs website
- *
- * This script creates static HTML files for each documentation version, renders page titles
- * using Liquid templating, and opens the generated TOC in your browser for easy navigation
- * during development. Supports command-line options to specify which sections should be
- * open by default.
- *
- * Usage: tsx src/dev-toc/generate.ts [-o product-ids...]
- */
+// @purpose Writer tool
+// @description Generate a local table of contents for the GitHub Docs website
+//
+// Creates static HTML for each documentation version, renders Liquid page titles, and opens the
+// generated table of contents in your browser. Use -o product-ids... to open sections by default.
+//
+// Run with: tsx src/dev-toc/generate.ts [-o product-ids...]
import fs from 'fs'
import path from 'path'
diff --git a/src/dev-toc/layout.html b/src/dev-toc/layout.html
index 24d8fab8fccd..78c08dde5811 100644
--- a/src/dev-toc/layout.html
+++ b/src/dev-toc/layout.html
@@ -38,7 +38,6 @@ TOC for {{ allVersions[currentVersion].versio
{{ productPage.renderedFullTitle }}
- {% comment %} Unified nested rendering with depth control {% endcomment %}
{% if productPage.childPages and productPage.childPages.size > 0 %}
{% for l1 in productPage.childPages %}
diff --git a/src/early-access/middleware/early-access-links.ts b/src/early-access/middleware/early-access-links.ts
index a09dfdc939f5..b9ac7d0f7cbd 100644
--- a/src/early-access/middleware/early-access-links.ts
+++ b/src/early-access/middleware/early-access-links.ts
@@ -8,13 +8,11 @@ export default function earlyAccessContext(
res: Response,
next: NextFunction,
) {
- // Use req.pagePath instead of req.path because req.path is the path
- // normalized after "converting" that `/_next/data/...` path to the
- // equivalent path if it had *not* been a client-side routing fetch.
+ // handleNextDataPath sets converted routes in req.pagePath; req.path keeps the /_next/data URL.
const url = req.pagePath!.split('/').slice(2)
if (
!(
- // Is it `/early-access` or `/enterprise-cloud@latest/early-access`?
+ // Match /early-access and versioned /early-access routes.
(
(url.length === 2 && url[1] === 'early-access') ||
(url.length === 1 && url[0] === 'early-access')
@@ -45,7 +43,7 @@ export default function earlyAccessContext(
.sort()
.map((permalink) => `- [${permalink.title}](${permalink.href})`)
- // Only read by the separate EA repo, in local development.
+ // Only the separate early access repo reads this, in local development.
req.context.earlyAccessPageLinks = earlyAccessPageLinks.length
? earlyAccessPageLinks.join('\n')
: '_None for this version!_'
diff --git a/src/early-access/scripts/clone-locally b/src/early-access/scripts/clone-locally
index ab816c586dba..4564e5f83a04 100755
--- a/src/early-access/scripts/clone-locally
+++ b/src/early-access/scripts/clone-locally
@@ -5,7 +5,6 @@
set -e
-# Go up a directory
pushd .. > /dev/null
if [ -d "docs-early-access" ]; then
@@ -14,13 +13,10 @@ if [ -d "docs-early-access" ]; then
exit 0
fi
-# Clone the repo
git clone https://github.com/github/docs-early-access.git
-# Go back to the previous working directory
popd > /dev/null
-# Symlink the local docs-early-access repo into this repo
npm run symlink-from-local-repo -- -p ../docs-early-access
echo -e '\nDone!'
diff --git a/src/early-access/scripts/create-branch b/src/early-access/scripts/create-branch
index c5f6fb6fad46..456e98db95ae 100755
--- a/src/early-access/scripts/create-branch
+++ b/src/early-access/scripts/create-branch
@@ -5,7 +5,6 @@
set -e
-# Get current branch name
currentBranch=$(git rev-parse --abbrev-ref HEAD)
if [ $currentBranch == "main" ]; then
@@ -13,7 +12,6 @@ if [ $currentBranch == "main" ]; then
exit 0
fi
-# Go up a directory
pushd .. > /dev/null
if [ ! -d "docs-early-access" ]; then
@@ -22,17 +20,13 @@ if [ ! -d "docs-early-access" ]; then
exit 0
fi
-# Navigate to docs-early-access
cd docs-early-access
-# Check out main and update
git checkout main
git pull origin main
-# Create a branch with the current docs-internal branch name
git checkout -b $currentBranch
-# Go back to the previous working directory
popd > /dev/null
echo -e "\nDone! Created a branch called ${currentBranch}. Remember to commit your work in ../docs-early-access when you're ready."
diff --git a/src/early-access/scripts/merge-early-access.sh b/src/early-access/scripts/merge-early-access.sh
index 8c70e549dc4c..00df810ca60d 100755
--- a/src/early-access/scripts/merge-early-access.sh
+++ b/src/early-access/scripts/merge-early-access.sh
@@ -1,10 +1,6 @@
#!/usr/bin/env bash
-# [start-readme]
-#
-# This script takes docs-early-access files and merges them into docs-internal
-#
-# [end-readme]
+# Merges docs-early-access files into docs-internal.
mv docs-early-access/assets/images assets/images/early-access
mv docs-early-access/content content/early-access
diff --git a/src/early-access/scripts/migrate-early-access-product.ts b/src/early-access/scripts/migrate-early-access-product.ts
index ef7e6cf2ae6f..0dbedc8430ea 100644
--- a/src/early-access/scripts/migrate-early-access-product.ts
+++ b/src/early-access/scripts/migrate-early-access-product.ts
@@ -1,8 +1,4 @@
-// [start-readme]
-//
-// Move the files from an early-access product level docs set into an existing product.
-//
-// [end-readme]
+// Moves a product-level early access docs set into an existing product.
import fs from 'fs'
import path from 'path'
@@ -54,7 +50,7 @@ if (!filesToMigrate.length) {
const migratePath: string = path.posix.join(contentDir, newPathId)
-// Update the image and data refs in the to-be-migrated early access files BEFORE moving them.
+// Rewrite early access image and data refs before moving files.
try {
execFileSync('tsx', [
'src/early-access/scripts/update-data-and-image-paths.ts',
@@ -71,7 +67,7 @@ const variablesToMove: string[] = []
const reusablesToMove: string[] = []
const imagesToMove: string[] = []
-// Add redirects to and update frontmatter in the to-be-migrated early access files BEFORE moving them.
+// Apply redirects and frontmatter changes before moving files.
for (const filepath of filesToMigrate) {
const { content, data } = frontmatter(fs.readFileSync(filepath, 'utf8'))
const redirectString: string = filepath
@@ -86,7 +82,6 @@ for (const filepath of filesToMigrate) {
fs.writeFileSync(filepath, frontmatter.stringify(content || '', data))
}
- // Find the data files and images referenced in the early access files so we can move them over.
const dataRefs: string[] = content ? content.match(patterns.dataReference) || [] : []
const variables: string[] = dataRefs.filter((ref) => ref.includes('variables'))
const reusables: string[] = dataRefs.filter((ref) => ref.includes('reusables'))
@@ -97,7 +92,6 @@ for (const filepath of filesToMigrate) {
imagesToMove.push(...images)
}
-// Move the data files and images.
for (const varRef of Array.from(new Set(variablesToMove))) {
moveVariable(varRef)
}
@@ -108,10 +102,8 @@ for (const imageRef of Array.from(new Set(imagesToMove))) {
moveImage(imageRef)
}
-// Move the content files.
execFileSync('mv', [oldPath, migratePath])
-// Update the parent product TOC with the new child path.
const parentProductTocPath: string = path.posix.join(path.dirname(newPath), 'index.md')
const parentProductToc = frontmatter(fs.readFileSync(parentProductTocPath, 'utf-8'))
if (parentProductToc.data && Array.isArray(parentProductToc.data.children)) {
@@ -123,7 +115,6 @@ fs.writeFileSync(
frontmatter.stringify(parentProductToc.content || '', parentProductToc.data || {}),
)
-// Optionally, update the new product TOC with the new title.
if (program.opts().newTitle) {
const productTocPath: string = path.posix.join(newPath, 'index.md')
const productToc = frontmatter(fs.readFileSync(productTocPath, 'utf-8'))
@@ -137,7 +128,6 @@ if (program.opts().newTitle) {
)
}
-// Update internal links now that the files have been moved.
console.log('\nRunning script to update internal links...')
execFileSync('tsx', ['src/links/scripts/update-internal-links.ts'])
@@ -153,18 +143,15 @@ Please review all the changes in docs-internal and docs-early-access, especially
`)
function moveVariable(dataRef: string): void {
- // Get the data filepath from the data reference,
- // where the data reference looks like: {% data variables.foo.bar %}
- // and the data filepath looks like: data/variables/foo.yml with key of 'bar'.
+ // Variable refs like {% data variables.foo.bar %} map to data/variables/foo.yml plus key bar.
const variablePathArray: string[] =
dataRef
.match(/{% (?:data|indented_data_reference) (.*?) %}/)?.[1]
.split('.')
- // If early access is part of the path, remove it (since the path below already includes it)
+ // Remove early-access because the path already joins under data/early-access.
.filter((n) => n !== 'early-access') || []
- // In `variables.foo.bar` the last segment is the variable key.
- // Pop it off, leaving the filepath `variables/foo.yml`.
+ // The last segment is the variable key; the remaining segments form variables/foo.yml.
const variableKey: string = last(variablePathArray) as string
variablePathArray.pop()
@@ -218,14 +205,12 @@ function moveVariable(dataRef: string): void {
}
function moveReusable(dataRef: string): void {
- // Get the data filepath from the data reference,
- // where the data reference looks like: {% data reusables.foo.bar %}
- // and the data filepath looks like: data/reusables/foo/bar.md.
+ // Reusable refs like {% data reusables.foo.bar %} map to data/reusables/foo/bar.md.
const reusablePath: string =
dataRef
.match(/{% (?:data|indented_data_reference) (\S*?) .*%}/)?.[1]
.split('.')
- // If early access is part of the path, remove it (since the path below already includes it)
+ // Remove early-access because the path already joins under data/early-access.
.filter((n) => n !== 'early-access')
.join('/') || ''
@@ -254,7 +239,7 @@ function moveReusable(dataRef: string): void {
function moveImage(imageRef: string): void {
const imagePath: string = imageRef
.replace('/assets/images/', '')
- // If early access is part of the path, remove it (since the path below already includes it)
+ // Remove early-access because the path already joins under assets/images/early-access.
.replace('early-access', '')
const oldImagePath: string = path.posix.join(
diff --git a/src/early-access/scripts/symlink-from-local-repo.ts b/src/early-access/scripts/symlink-from-local-repo.ts
index 43ef6423ec9c..59040f0a295b 100644
--- a/src/early-access/scripts/symlink-from-local-repo.ts
+++ b/src/early-access/scripts/symlink-from-local-repo.ts
@@ -1,7 +1,5 @@
-/**
- * @purpose Writer tool
- * @description Create or destroy symlinks to your local docs-early-access checkout
- */
+// @purpose Writer tool
+// @description Create or destroy symlinks to your local docs-early-access checkout
import fs from 'fs'
import path from 'path'
@@ -64,7 +62,6 @@ const destinationDirsMap: Record = destinationDirNames.reduce(
{} as Record,
)
-// Remove all existing early access directories from this repo
for (const dirName of destinationDirNames) {
const destDir = destinationDirsMap[dirName]
fs.rmSync(destDir, { recursive: true, force: true })
@@ -75,7 +72,6 @@ if (unlink) {
process.exit(0)
}
-// Symlink the latest early access source directories into this repo
for (const dirName of destinationDirNames) {
if (!earlyAccessLocalRepoDir) continue
diff --git a/src/early-access/scripts/update-data-and-image-paths.ts b/src/early-access/scripts/update-data-and-image-paths.ts
index f1823f9e1187..c7220d4f0803 100644
--- a/src/early-access/scripts/update-data-and-image-paths.ts
+++ b/src/early-access/scripts/update-data-and-image-paths.ts
@@ -1,7 +1,5 @@
-/**
- * @purpose Writer tool
- * @description Add or remove "early-access" from data and image paths
- */
+// @purpose Writer tool
+// @description Add or remove "early-access" from data and image paths
import fs from 'fs'
import path from 'path'
@@ -45,7 +43,7 @@ let selectedFiles: string[] = allEarlyAccessFiles
if (earlyAccessPath) {
const contentFiles = allEarlyAccessFiles.filter((file) => file.includes(earlyAccessPath))
- // We also need to include any reusable files that are referenced in the selected content files.
+ // Include reusable files referenced by selected content files.
const referencedDataFiles: string[] = []
for (const file of contentFiles) {
const contents = fs.readFileSync(file, 'utf8')
diff --git a/src/early-access/scripts/what-docs-early-access-branch.ts b/src/early-access/scripts/what-docs-early-access-branch.ts
index fd69e85f1c1c..41e89a0ff5f9 100644
--- a/src/early-access/scripts/what-docs-early-access-branch.ts
+++ b/src/early-access/scripts/what-docs-early-access-branch.ts
@@ -16,9 +16,7 @@ async function main(): Promise {
const OUTPUT_KEY = 'branch'
- // If being run from a PR, this becomes 'my-cool-branch'.
- // If run on main, with the `workflow_dispatch` action for
- // example, the value becomes 'main'.
+ // Use the matching docs-early-access branch when it exists; 404 falls back to main.
const github = getOctokit(GITHUB_TOKEN)
for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
@@ -39,7 +37,7 @@ async function main(): Promise {
setOutput(OUTPUT_KEY, 'main')
return
}
- // Retry on network/server errors (5xx, timeouts, etc.)
+ // Retry any non-404 failure until MAX_RETRIES is reached.
if (attempt < MAX_RETRIES) {
console.warn(
`Attempt ${attempt}/${MAX_RETRIES} failed with error: ${err instanceof Error ? err.message : String(err)}. Retrying in ${RETRY_DELAY_SECONDS}s...`,
diff --git a/src/early-access/tests/early-access-unit.ts b/src/early-access/tests/early-access-unit.ts
index d133f1479a12..a5b267b1ca34 100644
--- a/src/early-access/tests/early-access-unit.ts
+++ b/src/early-access/tests/early-access-unit.ts
@@ -28,7 +28,7 @@ describeIfDocsEarlyAccess('early access rendering', () => {
test('404 if any other language than English', async () => {
for (const code of Object.keys(languages)) {
if (code === 'en') {
- // This is tested elsewhere
+ // English early access rendering has separate tests above.
continue
}
const res = await get(`/${code}${VALID_EARLY_ACCESS_URI}`)
diff --git a/src/eslint-rules/no-dangerously-set-inner-html/no-dangerously-set-inner-html.js b/src/eslint-rules/no-dangerously-set-inner-html/no-dangerously-set-inner-html.js
index 75b90dbc8b14..174e8a8856bf 100644
--- a/src/eslint-rules/no-dangerously-set-inner-html/no-dangerously-set-inner-html.js
+++ b/src/eslint-rules/no-dangerously-set-inner-html/no-dangerously-set-inner-html.js
@@ -15,17 +15,12 @@ module.exports = {
},
create(context) {
return {
- // Flag the JSX attribute form:
JSXAttribute(node) {
if (node.name && node.name.name === "dangerouslySetInnerHTML") {
context.report({ node, messageId: "noDanger" });
}
},
- // Flag the object-property form used when spreading props, e.g.
- // { dangerouslySetInnerHTML: { __html: html } }. Only object *expressions*
- // (constructing props) are unsafe; skip object *patterns* (destructuring
- // like `const { dangerouslySetInnerHTML, ...rest } = props`), which strip
- // the prop and are safe.
+ // Object expressions can build JSX-spread dangerouslySetInnerHTML; patterns only read props.
Property(node) {
if (!node.parent || node.parent.type !== "ObjectExpression") return;
const key = node.key;
@@ -38,9 +33,7 @@ module.exports = {
context.report({ node, messageId: "noDanger" });
}
},
- // Flag the assignment form, including the computed string-key bypass:
- // props.dangerouslySetInnerHTML = { __html: html }
- // props['dangerouslySetInnerHTML'] = { __html: html }
+ // Direct and computed assignments bypass JSX-attribute checks, so flag both forms.
AssignmentExpression(node) {
const left = node.left;
if (!left || left.type !== "MemberExpression") return;
diff --git a/src/eslint-rules/no-dangerously-set-inner-html/tests/no-dangerously-set-inner-html.ts b/src/eslint-rules/no-dangerously-set-inner-html/tests/no-dangerously-set-inner-html.ts
index 399ef0225838..c5a80d0189aa 100644
--- a/src/eslint-rules/no-dangerously-set-inner-html/tests/no-dangerously-set-inner-html.ts
+++ b/src/eslint-rules/no-dangerously-set-inner-html/tests/no-dangerously-set-inner-html.ts
@@ -21,7 +21,7 @@ describe('no-dangerously-set-inner-html', () => {
{ code: `const el = ((resolve) => {
releaseNavigation = resolve
@@ -261,24 +239,16 @@ test('sidebar highlights the clicked item optimistically while navigation is pen
await helloWorld.click()
- // While pending: the clicked link carries the optimistic visual marker, but the URL
- // and the semantic aria-current still reflect the (still-loaded) get-started page.
await expect(helloWorld).toHaveAttribute('data-pending', '')
await expect(helloWorld).not.toHaveAttribute('aria-current', 'page')
await expect(page).not.toHaveURL(/hello-world/)
- // Let the navigation finish: the marker gives way to a real aria-current.
releaseNavigation()
await expect(page).toHaveURL(/\/en\/get-started\/start-your-journey\/hello-world/)
await expect(helloWorld).toHaveAttribute('aria-current', 'page')
await expect(helloWorld).not.toHaveAttribute('data-pending', '')
- // A modifier-click (open in new tab) must NOT move the optimistic selection.
- // handleNavClick bails on modifier clicks, so pendingHref is never set: the current
- // page keeps its URL, its aria-current, and the clicked link gets no data-pending.
- // Use ControlOrMeta so the real "open in new tab" modifier is sent per-platform
- // (Ctrl on Linux/Windows CI, Meta on macOS). The click opens a background tab we
- // don't need to assert on; catch any popup so it doesn't leak.
+ // handleNavClick skips modifier clicks; ControlOrMeta must not set pendingHref. Close the popup.
page.on('popup', (popup) => popup.close())
await linkRewriting.click({ modifiers: ['ControlOrMeta'] })
await expect(linkRewriting).not.toHaveAttribute('data-pending', '')
@@ -290,18 +260,15 @@ test('press "/" to open the search overlay', async ({ page }) => {
await page.goto('/')
await turnOffExperimentsInPage(page)
- // Wait for the header search button to render, so the keydown listener is attached.
+ // The keydown listener attaches when the header search button renders.
await page.getByTestId('toggle-search').waitFor()
const searchInput = page.getByTestId('overlay-search-input')
- // The overlay (and its input) is not in the DOM until it's opened.
await expect(searchInput).toHaveCount(0)
- // Pressing "/" anywhere on the page opens the overlay and focuses the input.
await page.keyboard.press('/')
await expect(searchInput).toBeFocused()
- // Escape closes it again and returns focus to the same responsive trigger.
await page.keyboard.press('Escape')
await expect(searchInput).toHaveCount(0)
await expect(page.getByTestId('toggle-search')).toBeFocused()
@@ -317,7 +284,7 @@ test('"/" typed inside the search input is a literal slash', async ({ page }) =>
const searchInput = page.getByTestId('overlay-search-input')
await expect(searchInput).toBeFocused()
- // The "/" shortcut must not fire while typing in a field, so it is not swallowed.
+ // The slash shortcut must not fire while typing in a field.
await page.keyboard.type('a/b')
await expect(searchInput).toHaveValue('a/b')
})
@@ -352,11 +319,8 @@ test('open search, and perform a general search', async ({ page }) => {
await page.getByTestId('toggle-search').click()
await page.getByTestId('overlay-search-input').fill('serve playwright')
- // Wait for the results to load
- // NOTE: In the UI we wait for results to load before allowing "enter", because we don't want
- // to allow an unnecessary request when there are no search results. Easier to wait 1 second
+ // Wait 1 second for results to load, because the UI blocks submitting the query until then.
await page.waitForTimeout(1000)
- // Scroll down to "View all results" then press enter
await page.getByText('View more results').click()
await expect(page).toHaveURL(
@@ -364,7 +328,6 @@ test('open search, and perform a general search', async ({ page }) => {
)
await expect(page).toHaveTitle(/\d Search results for "serve playwright"/)
- // The first result should be "For Playwright"
await page.getByRole('link', { name: 'For Playwright' }).click()
await expect(page).toHaveURL(/\/get-started\/foo\/for-playwright$/)
@@ -379,13 +342,11 @@ test('open search, and select a general search article', async ({ page }) => {
await page.getByTestId('toggle-search').click()
await page.getByTestId('overlay-search-input').fill('serve playwright')
- // Let new suggestions load
const searchOverlay = page.getByTestId('general-autocomplete-suggestions')
await expect(searchOverlay.getByText('For Playwright')).toBeVisible()
await page.keyboard.press('ArrowDown')
await page.keyboard.press('Enter')
- // We should now be on the page for "For Playwright"
await expect(page).toHaveURL(/\/get-started\/foo\/for-playwright$/)
await expect(page).toHaveTitle(/For Playwright/)
})
@@ -403,7 +364,7 @@ test('open search, and get auto-complete results', async ({ page }) => {
let listItems = listGroup.locator('li')
await expect(listItems).toHaveCount(4)
- // Top queries from queries.json fixture's 'topQueries'
+ // The first list mirrors queries.json fixture topQueries.
let expectedTexts = [
'What is GitHub and how do I get started?',
'What is GitHub Copilot and how do I get started?',
@@ -422,7 +383,6 @@ test('open search, and get auto-complete results', async ({ page }) => {
await searchInput.fill('rest')
await page.waitForTimeout(1000)
- // Ask AI suggestions
listGroup = page.getByTestId('ai-autocomplete-suggestions')
listItems = listGroup.locator('li')
await expect(listItems).toHaveCount(3)
@@ -448,20 +408,14 @@ test('search from enterprise-cloud and filter by top-level Fooing', async ({ pag
await page.waitForTimeout(1000)
await page.getByText('View more results').click()
- // Now we're on the search results page, apply the filter
await page.getByText('Fooing (1)').click()
await page.getByRole('link', { name: 'Clear' }).click()
-
- // At the moment this test isn't great because it's not proving that
- // certain things cease to be visible, that was visible before. Room
- // for improvement!
})
test('404 page renders correctly', async ({ page }) => {
const response = await page.goto('/this-definitely-does-not-exist')
expect(response?.status()).toBe(404)
- // 404 pages now render a minimal HTML response
await expect(page.getByText('Page not found.')).toBeVisible()
})
@@ -507,7 +461,6 @@ test.describe('platform picker', () => {
await turnOffExperimentsInPage(page)
await page.getByTestId('platform-picker').getByRole('link', { name: 'Windows' }).click()
- // Return and now the cookie should start us off on Windows again
await page.goto('/get-started/liquid/platform-specific')
await expect(page.getByRole('heading', { name: /Windows 95/ })).toBeVisible()
await expect(page.getByRole('heading', { name: /Macintosh/ })).not.toBeVisible()
@@ -534,7 +487,7 @@ test.describe('tool picker', () => {
test('prefer default tool', async ({ page }) => {
await page.goto('/get-started/liquid/tool-specific')
- // defaultTool is set in the fixture frontmatter to webui
+ // The fixture frontmatter defaults defaultTool to webui.
await expect(page.getByText('This is webui content')).toBeVisible()
await expect(page.getByText('This is desktop content')).not.toBeVisible()
await expect(page.getByText('This is cli content')).not.toBeVisible()
@@ -545,7 +498,6 @@ test.describe('tool picker', () => {
await turnOffExperimentsInPage(page)
await page.getByTestId('tool-picker').getByRole('link', { name: 'Web browser' }).click()
- // Return and now the cookie should start us off with Web UI content again
await page.goto('/get-started/liquid/tool-specific')
await expect(page.getByText('This is cli content')).not.toBeVisible()
await expect(page.getByText('This is desktop content')).not.toBeVisible()
@@ -553,10 +505,9 @@ test.describe('tool picker', () => {
})
test('minitoc matches picker', async ({ page }) => {
- // See the note on the platform-specific version of this test: don't sit on
- // the drawer's exact reveal breakpoint.
+ // Avoid the drawer's exact reveal breakpoint.
await page.setViewportSize({ width: 1440, height: 900 })
- // default tool set to webui in fixture frontmatter
+ // The fixture frontmatter defaults defaultTool to webui.
await page.goto('/get-started/liquid/tool-specific')
await turnOffExperimentsInPage(page)
await expect(
@@ -616,9 +567,7 @@ test.describe('code tabs', () => {
test('navigate with side bar into article inside a subcategory inside a category', async ({
page,
}) => {
- // Our TreeView sidebar only shows "2 levels". If you click and expand
- // the category, you'll be able to see the subcategory and the article
- // within.
+ // The TreeView sidebar shows two levels until the category expands.
await page.goto('/actions')
await page.getByTestId('sidebar').getByText('Category', { exact: true }).click()
await page.getByTestId('sidebar').getByText('Subcategory').click()
@@ -645,7 +594,6 @@ test.describe('hover cards', () => {
await page.goto('/pages/quickstart')
await turnOffExperimentsInPage(page)
- // hover over a link and check for intro content from hovercard
await page
.locator('#article-contents')
.getByRole('link', { name: 'Start your journey' })
@@ -656,8 +604,6 @@ test.describe('hover cards', () => {
),
).toBeVisible()
- // now move the mouse away from hovering over the link, the hovercard should
- // no longer be visible
await page.mouse.move(0, 0)
await expect(
page.getByText(
@@ -665,38 +611,31 @@ test.describe('hover cards', () => {
),
).not.toBeVisible()
- // external links don't have a hovercard
await page.getByRole('link', { name: 'github.com/github/docs' }).hover()
await expect(page.getByTestId('popover')).not.toBeVisible()
- // links in the main navigation sidebar don't have a hovercard
await page.getByTestId('sidebar').getByRole('link', { name: 'Quickstart' }).hover()
await expect(page.getByTestId('popover')).not.toBeVisible()
- // links in the secondary minitoc sidebar don't have a hovercard
await page
.getByTestId('minitoc')
.getByRole('link', { name: 'Regular internal link', exact: true })
.hover()
await expect(page.getByTestId('popover')).not.toBeVisible()
- // links in the article intro have a hovercard
await page.locator('#article-intro').getByRole('link', { name: 'article intro link' }).hover()
await expect(page.getByText('You can use HubGit Pages to showcase')).toBeVisible()
- // this page's intro has two links; one in-page and one internal
await page.locator('#article-intro').getByRole('link', { name: 'another link' }).hover()
await expect(
page.getByText('Follow this Hello World exercise to get started with HubGit.'),
).toBeVisible()
- // same page anchor links have a hovercard
await page
.locator('#article-contents')
.getByRole('link', { name: 'introduction', exact: true })
.hover()
await expect(page.getByText('You can use HubGit Pages to showcase')).toBeVisible()
- // links with formatted text need to work too
await page.locator('#article-contents').getByRole('link', { name: 'Bold is strong' }).hover()
await expect(page.getByText('The most basic of fixture data for HubGit')).toBeVisible()
await page.locator('#article-contents').getByRole('link', { name: 'bar' }).hover()
@@ -707,7 +646,6 @@ test.describe('hover cards', () => {
await page.goto('/pages/quickstart')
await turnOffExperimentsInPage(page)
- // Simply putting focus on the link should not open the hovercard
await page
.locator('#article-contents')
.getByRole('link', { name: 'Start your journey' })
@@ -718,7 +656,6 @@ test.describe('hover cards', () => {
),
).not.toBeVisible()
- // Once a link has got focus, you can use Alt+ArrowUp to open the hovercard
await page.keyboard.press('Alt+ArrowUp')
await expect(
page.getByText(
@@ -738,7 +675,6 @@ test.describe('hover cards', () => {
await page.goto('/pages/quickstart')
await turnOffExperimentsInPage(page)
- // hover over a link and check for intro content from hovercard
await page
.locator('#article-contents')
.getByRole('link', { name: 'Start your journey' })
@@ -766,9 +702,7 @@ test.describe('test nav at different viewports', () => {
})
await page.goto('/get-started/foo/bar')
- // The Docs 2026 secondary bar leads with a Home crumb, then the full trail
- // 'Get started / Foo / Bar' (no hidden last crumb). The current page is
- // static text rather than a link, so only the three ancestors are links.
+ // Breadcrumbs include Home and the full trail; only the three ancestors are links.
expect(await page.getByTestId('breadcrumbs-bar').getByRole('link').all()).toHaveLength(3)
await expect(page.getByTestId('breadcrumbs-bar').locator('[aria-current="page"]')).toHaveText(
'Bar',
@@ -776,64 +710,51 @@ test.describe('test nav at different viewports', () => {
await expect(page.getByTestId('breadcrumbs-bar').getByText('Foo')).toBeVisible()
await expect(page.getByTestId('breadcrumbs-bar').getByText('Bar')).toBeVisible()
- // breadcrumbs show up in rest reference pages
await page.goto('/rest/actions/artifacts')
await expect(page.getByTestId('breadcrumbs-bar')).toBeVisible()
- // breadcrumbs show up in one of the pages that use the AutomatedPage
- // component (e.g. graphql, audit log). This one uses the webhooks
- // reference page here
+ // Webhooks renders through an AutomatedPage reference page, which shows breadcrumbs.
await page.goto('/webhooks/webhook-events-and-payloads')
await expect(page.getByTestId('breadcrumbs-bar')).toBeVisible()
})
test('mobile nav opens even when the desktop rail was collapsed', async ({ page }) => {
- // Collapse the desktop rail with both drawers out (xxl) so the persisted
- // `collapsed` state is set via the secondary-bar collapse toggle.
+ // At xxl with both drawers out, the secondary-bar collapse toggle persists collapsed.
page.setViewportSize({
width: 1400,
height: 700,
})
await page.goto('/get-started/foo/bar')
await page.getByTestId('sidebar-collapse-toggle').click()
- // With the rail collapsed the sidebar is not rendered on desktop.
await expect(page.getByTestId('sidebar')).toHaveCount(0)
- // Drop below lg (1012) where the inline mobile nav toggle lives (Docs 2026:
- // the lg–xxl range keeps the desktop collapse toggle instead). `collapsed`
- // persists across the resize.
+ // Below lg 1012px, the inline mobile nav toggle replaces the desktop collapse toggle.
page.setViewportSize({
width: 1000,
height: 700,
})
- // Opening the mobile nav must still render the doc-tree drawer. Before the
- // fix, `collapsed` short-circuited the sidebar to null while the open state
- // hid the content column, leaving a blank area with no drawer.
+ // Mobile nav must render the doc-tree drawer even with persisted collapsed state.
await page.getByTestId('sidebar-mobile-toggle').click()
await expect(page.getByTestId('sidebar')).toBeVisible()
- // Closing it restores the content column (main content visible again).
await page.getByTestId('sidebar-mobile-toggle').click()
await expect(page.locator('#main-content')).toBeVisible()
})
test('resizing from mobile to desktop closes the inline nav', async ({ page }) => {
- // Start below the lg (1012px) breakpoint where the inline mobile nav lives.
+ // Below lg 1012px, the inline mobile nav lives in the secondary bar.
await page.setViewportSize({
width: 1000,
height: 700,
})
await page.goto('/get-started/foo/bar')
- // Open the inline doc-tree nav from the secondary bar.
await page.getByTestId('sidebar-mobile-toggle').click()
const nav = page.locator('[data-container="nav"]')
await expect(nav).toHaveAttribute('data-mobile-open', 'true')
- // Resize up to the desktop breakpoint. The inline nav should close and the
- // fixed desktop rail (326px) should take over rather than the full-width
- // mobile markup persisting over the page.
+ // At 1400px, the desktop rail is 326px and replaces full-width mobile markup.
await page.setViewportSize({
width: 1400,
height: 700,
@@ -849,7 +770,6 @@ test.describe('test nav at different viewports', () => {
})
await page.goto('/get-started/foo/bar')
- // Both complete pickers are visible directly in the wide header.
await expect(
page.getByTestId('version-picker').getByText('Select your plan:', { exact: true }),
).toBeVisible()
@@ -863,7 +783,6 @@ test.describe('test nav at different viewports', () => {
await page.keyboard.press('Escape')
await expect(planMenu).not.toBeVisible()
- // The language picker is the same kind of nested dropdown as the plan one.
const languageButton = page.getByRole('button', {
name: 'Select language: current language is English',
})
@@ -887,15 +806,10 @@ test.describe('test nav at different viewports', () => {
})
await page.goto('/get-started/foo/bar')
- // breadcrumbs show up in the secondary bar; for this page we should have
- // a Home crumb plus 'Get started / Foo / Bar' — the last of which is the
- // current page, rendered as static text rather than a link.
await expect(page.getByTestId('breadcrumbs-bar')).toBeVisible()
expect(await page.getByTestId('breadcrumbs-bar').getByRole('link').all()).toHaveLength(3)
- // At lg+ (Docs 2026) the doc-tree rail is shown by default with the desktop
- // collapse toggle; the mobile inline-nav toggle is hidden. Clicking the
- // collapse toggle hides the rail.
+ // At lg+, the desktop rail shows and the inline-nav toggle hides.
await expect(page.getByTestId('sidebar')).toBeVisible()
await expect(page.getByTestId('sidebar-collapse-toggle')).toBeVisible()
await expect(page.getByTestId('sidebar-mobile-toggle')).toBeHidden()
@@ -945,8 +859,7 @@ test.describe('test nav at different viewports', () => {
await expect(languageMenu).not.toBeVisible()
await expect(page.getByTestId('header-signup')).toBeVisible()
- // The independent secondary-bar navigation is intentionally inert until the
- // modal header menu closes, then still expands the doc tree inline.
+ // The secondary-bar nav stays inert until the modal header menu closes.
await page.getByRole('button', { name: 'Close menu', exact: true }).click()
await expect(page.getByTestId('sidebar-mobile-toggle')).toBeVisible()
await page.getByTestId('sidebar-mobile-toggle').click()
@@ -998,13 +911,9 @@ test.describe('test nav at different viewports', () => {
})
test.describe('secondary-bar breadcrumb scroller', () => {
- // The secondary bar (and its breadcrumb scroller) only renders at wide
- // viewports, and the fixture trail is short enough to fit there, so we cap the
- // scroller width to force a deterministic overflow independent of title
- // lengths, then exercise the chevrons.
+ // Cap breadcrumb scroller width to force deterministic overflow.
test('chevrons scroll one crumb at a time instead of jumping to the ends', async ({ page }) => {
- // Smooth-scroll settle waits across several chevron clicks add up past the
- // default 5s cap.
+ // Several smooth-scroll waits can exceed the default 5s test cap.
test.setTimeout(20000)
page.setViewportSize({ width: 1300, height: 700 })
await page.goto('/get-started/foo/bar')
@@ -1015,11 +924,7 @@ test.describe('secondary-bar breadcrumb scroller', () => {
const scrollArea = page.locator('[data-search="breadcrumbs"]')
await expect(scrollArea).toBeVisible()
- // Force a deterministic overflow independent of title lengths: cap the
- // scroll region, drop the nav's min-width:100% (which otherwise stretches the
- // short fixture trail to fill the container so it never overflows), and pad
- // the crumbs so several are hidden at once — enough that a per-crumb nudge is
- // distinguishable from a jump to the end.
+ // Cap scroll width, remove nav min-width:100%, and pad crumbs to detect nudges.
await page.addStyleTag({
content: `
[data-search="breadcrumbs"] { max-width: 360px; }
@@ -1032,37 +937,28 @@ test.describe('secondary-bar breadcrumb scroller', () => {
const maxScrollOf = () => scrollArea.evaluate((el) => el.scrollWidth - el.clientWidth)
await expect.poll(maxScrollOf).toBeGreaterThan(0)
- // Anchor to the right end explicitly so we start from a known state: fully
- // scrolled right (current page visible), only the left chevron active.
+ // Start fully scrolled right so only the left chevron is active.
await scrollArea.evaluate((el) => el.scrollTo({ left: el.scrollWidth, behavior: 'instant' }))
const maxScroll = await maxScrollOf()
await expect.poll(scrollLeftOf).toBe(maxScroll)
const leftChevron = page.getByRole('button', { name: 'Scroll breadcrumbs left' })
const rightChevron = page.getByRole('button', { name: 'Scroll breadcrumbs right' })
- // At the right extreme the left chevron is active and the right one is hidden.
await expect(leftChevron).toBeVisible()
await expect(rightChevron).toBeHidden()
- // One left click nudges toward the start by a single crumb — it must move,
- // but must NOT jump all the way to 0 (the old behavior) while more than one
- // crumb is still hidden to the left.
+ // One left click must move without jumping to 0 while crumbs stay hidden left.
await leftChevron.click()
await expect.poll(scrollLeftOf).toBeLessThan(maxScroll)
const afterOneLeft = await scrollLeftOf()
expect(afterOneLeft).toBeGreaterThan(0)
- // The right chevron appears once we're no longer at the right extreme.
await expect(rightChevron).toBeVisible()
- // A right click walks back toward the current page by one crumb, not a full
- // jump back to the right extreme.
+ // Right click returns by one crumb, not a jump to the right extreme.
await rightChevron.click()
await expect.poll(scrollLeftOf).toBeGreaterThan(afterOneLeft)
- // Repeated left clicks eventually reach the start, which hides the left
- // chevron (canScrollLeft flips false). Drive off the chevron's own visibility
- // rather than an exact scrollLeft, since smooth scrolling can leave a
- // sub-pixel remainder.
+ // Drive off chevron visibility because smooth scrolling can leave sub-pixel scrollLeft.
for (let i = 0; i < 6 && (await leftChevron.isVisible()); i++) {
await leftChevron.click()
await page.waitForTimeout(200)
@@ -1073,16 +969,10 @@ test.describe('secondary-bar breadcrumb scroller', () => {
})
test.describe('anchor link scrolling', () => {
- // The doc-tree rail only renders at the xxl breakpoint (1400px) and up. Its
- // "centre the active item" effect used to call scrollIntoView, which scrolls
- // every scrollable ancestor including the document, so it undid the browser's
- // scroll to the #anchor and dumped the reader at the top of the article.
- // These tests only mean anything with the rail on screen.
+ // At xxl, centering the active doc-tree item can undo browser anchor scrolling.
const WIDE = { width: 1400, height: 720 }
- // The heading is offset from the top of the viewport by `scroll-margin-top`
- // (109px at xxl, see src/frame/stylesheets/scroll-top.scss). Allow slack for
- // rounding and sticky-header tweaks, but stay well clear of "not scrolled".
+ // scroll-margin-top is 109px at xxl; allow rounding and sticky-header slack, but reject an unscrolled page.
const expectScrolledToTarget = async (page: import('@playwright/test').Page) => {
const heading = page.locator('#target-heading')
await expect(heading).toBeVisible()
@@ -1096,10 +986,7 @@ test.describe('anchor link scrolling', () => {
await expect(page.getByTestId('sidebar')).toBeVisible()
await expectScrolledToTarget(page)
- // Guard the setup: the regression only shows when the rail has actually
- // scrolled its own container to centre the active item. If a fixture change
- // ever makes the rail short enough that it doesn't need to scroll, these
- // tests would keep passing while covering nothing — fail loudly instead.
+ // Fail if the fixture rail stops scrolling, because the test would cover nothing.
const railScrollTop = await page
.getByTestId('sidebar')
.evaluate((el) => el.closest('[role="region"]')!.scrollTop)
@@ -1135,8 +1022,7 @@ test.describe('survey', () => {
const surveyComment = 'This is a comment'
- // Important to set this up *before* interacting with the page
- // in case of possible race conditions.
+ // Install the route before interacting with the page to avoid event races.
await page.route('**/api/events', (route, request) => {
const postData = request.postData()
if (postData) {
@@ -1160,10 +1046,7 @@ test.describe('survey', () => {
}
}
}
- // At the time of writing you can't get the posted payload
- // when you use `navigator.sendBeacon(url, data)`.
- // So we can't make assertions about the payload.
- // See https://github.com/microsoft/playwright/issues/12231
+ // Chromium hides sendBeacon payloads from Playwright: https://github.com/microsoft/playwright/issues/12231
})
await page.addInitScript(() => {
@@ -1172,7 +1055,7 @@ test.describe('survey', () => {
await page.goto('/get-started/foo/for-playwright')
- // The label is visually an SVG. Finding it by its `for` value feels easier.
+ // The label renders as an SVG, so locate it by for=survey-yes.
await page.locator('[for=survey-yes]').click()
await expect(page.getByRole('button', { name: 'Cancel' })).toBeVisible()
await expect(page.getByRole('button', { name: 'Send' })).toBeVisible()
@@ -1181,7 +1064,6 @@ test.describe('survey', () => {
await page.locator('[name=survey-email]').click()
await page.locator('[name=survey-email]').fill('test@example.com')
await page.getByRole('button', { name: 'Send' }).click()
- // simulate sending an exit event to trigger sending all queued events
await page.evaluate(() => {
Object.defineProperty(document, 'visibilityState', {
configurable: true,
@@ -1193,11 +1075,7 @@ test.describe('survey', () => {
return new Promise((resolve) => setTimeout(resolve, 100))
})
- // Events:
- // 1. page view event when navigating to the page
- // 2. Survey thumbs up event
- // 3. Survey submit event
- // 4. Exit event
+ // fulfilled counts page view, survey thumbs up, survey submit, and exit events.
expect(fulfilled).toBe(1 + 1 + 1 + 1)
expect(hasSurveyPressedEvent).toBe(true)
expect(hasSurveySubmittedEvent).toBe(true)
@@ -1208,8 +1086,7 @@ test.describe('survey', () => {
let fulfilled = 0
let hasSurveyEvent = false
- // Important to set this up *before* interacting with the page
- // in case of possible race conditions.
+ // Install the route before interacting with the page to avoid event races.
await page.route('**/api/events', (route, request) => {
const postData = request.postData()
if (postData) {
@@ -1223,10 +1100,7 @@ test.describe('survey', () => {
}
}
}
- // At the time of writing you can't get the posted payload
- // when you use `navigator.sendBeacon(url, data)`.
- // So we can't make assertions about the payload.
- // See https://github.com/microsoft/playwright/issues/12231
+ // Chromium hides sendBeacon payloads from Playwright: https://github.com/microsoft/playwright/issues/12231
})
await page.addInitScript(() => {
@@ -1236,7 +1110,6 @@ test.describe('survey', () => {
await page.goto('/get-started/foo/for-playwright')
await page.locator('[for=survey-yes]').click()
- // simulate sending an exit event to trigger sending all queued events
await page.evaluate(() => {
Object.defineProperty(document, 'visibilityState', {
configurable: true,
@@ -1247,10 +1120,7 @@ test.describe('survey', () => {
document.dispatchEvent(new Event('visibilitychange'))
return new Promise((resolve) => setTimeout(resolve, 100))
})
- // Events:
- // 1. page view event when navigating to the page
- // 2. the thumbs up click
- // 3. the exit event
+ // fulfilled counts page view, thumbs up, and exit events.
expect(fulfilled).toBe(1 + 1 + 1)
expect(hasSurveyEvent).toBe(true)
@@ -1259,8 +1129,7 @@ test.describe('survey', () => {
})
test('vote on one page, then go to another and it should reset', async ({ page }) => {
- // Important to set this up *before* interacting with the page
- // in case of possible race conditions.
+ // Install the route before interacting with the page to avoid event races.
await page.route('**/api/events', (route) => {
route.fulfill({})
})
@@ -1284,12 +1153,10 @@ test.describe('survey', () => {
test.describe('rest API reference pages', () => {
test('REST actions', async ({ page }) => {
await page.goto('/rest')
- // Before using the sidebar, make sure the page has redirected to a
- // URL that has that `?apiVersion=` query parameter.
+ // Redirect must add the apiVersion query before sidebar navigation.
await expect(page).toHaveURL(/\/en\/rest\?apiVersion=/)
await page.getByTestId('sidebar').getByText('Actions').click()
- // Brand NavList renders leaf articles as links (not the label-associated
- // controls Primer used), so locate them by link role rather than getByLabel.
+ // Brand NavList renders leaf articles as links, not Primer's label-associated controls.
await page.getByTestId('sidebar').getByRole('link', { name: 'Artifacts' }).click()
await page
.getByTestId('sidebar')
@@ -1313,7 +1180,6 @@ test.describe('translations', () => {
await expect(page).toHaveURL('/ja')
await expect(page.getByRole('heading', { name: '日本 GitHub Docs' })).toBeVisible()
- // Having done this once, should now use a cookie to redirect back to Japanese
await page.goto('/')
await expect(page).toHaveURL('/ja')
})
@@ -1326,16 +1192,11 @@ test.describe('translations', () => {
await expect(page).toHaveURL('/ja/get-started/start-your-journey/hello-world')
await expect(page.getByRole('heading', { name: 'こんにちは World' })).toBeVisible()
- // Having done this once, should now use a cookie to redirect
- // back to Japanese.
- // Playwright will cache this redirect, so we need to add something
- // to "cache bust" the URL
+ // Bust the URL because Playwright caches the redirect back to Japanese.
const cb = `?cb=${Math.random()}`
await page.goto(`/get-started/start-your-journey/hello-world${cb}`)
await expect(page).toHaveURL(`/ja/get-started/start-your-journey/hello-world${cb}`)
- // If you go, with the Japanese cookie, to the English page directly,
- // it will offer a link to the Japanese URL in a banner.
await page.goto('/en/get-started/start-your-journey/hello-world')
await expect(page).toHaveURL('/ja/get-started/start-your-journey/hello-world')
})
@@ -1344,9 +1205,7 @@ test.describe('translations', () => {
test('open search, and ask Copilot (Ask AI) a question', async ({ page }) => {
test.skip(!SEARCH_TESTS, 'No local Elasticsearch, no tests involving search')
- // Mock the CSE Copilot endpoint
await page.route('**/api/ai-search/v1', async (route) => {
- // Simulate the streaming response from CSE Copilot
const mockResponse = `{"chunkType":"SOURCES","sources":[{"title":"Creating a new repository","index":"/en/get-started","url":"http://localhost:4000/en/get-started"}]}
{"chunkType":"MESSAGE_CHUNK","text":"Creating "}
@@ -1380,31 +1239,23 @@ test('open search, and ask Copilot (Ask AI) a question', async ({ page }) => {
await page.getByTestId('toggle-search').click()
await page.getByTestId('overlay-search-input').fill('How do I create a Repository?')
- // Pressing enter should ask AI the question
await page.keyboard.press('Enter')
- // Wait for the AI response to appear
await expect(page.getByText('Creating a repository on GitHub')).toBeVisible()
- // Verify that sources are displayed
await expect(page.getByText('Creating a new repository')).toBeVisible()
- // Verify the full response appears
await expect(page.getByText('something you should already know how to do')).toBeVisible()
- // Open the "Creating new repository" source link list item
- // Find the references section first
const aiReferencesSection = page.getByTestId('ai-references')
await expect(aiReferencesSection).toBeVisible()
- // Wait for the reference list to be populated
await expect(page.getByText('Creating a new repository')).toBeVisible()
})
test('open search, Ask AI returns 400 error and shows general search results', async ({ page }) => {
test.skip(!SEARCH_TESTS, 'No local Elasticsearch, no tests involving search')
- // Mock the CSE Copilot endpoint to return a 400 error
await page.route('**/api/ai-search/v1', async (route) => {
await route.fulfill({
status: 400,
@@ -1422,21 +1273,16 @@ test('open search, Ask AI returns 400 error and shows general search results', a
await page.getByTestId('toggle-search').click()
await page.getByTestId('overlay-search-input').fill('foo')
- // Pressing enter should trigger Ask AI, get 400 error, and show general search results
await page.keyboard.press('Enter')
- // Wait for the general search results to appear inside the overlay's suggestions
- // group. These render as ActionList items (buttons), so scope the lookup to the
- // group rather than matching page-level links of the same name.
+ // Search suggestions render as ActionList buttons, so scope Foo and Bar to the suggestion group.
const generalSuggestions = page.getByTestId('general-autocomplete-suggestions')
await expect(generalSuggestions.getByRole('button', { name: 'Foo' })).toBeVisible()
await expect(generalSuggestions.getByRole('button', { name: 'Bar' })).toBeVisible()
- // Wait for the AI error message to appear
- // This is a canned response for the 400 error
- await page.waitForTimeout(1000) // Wait for the AI error message to appear
+ // Wait for the canned 400 response before checking the paragraph.
+ await page.waitForTimeout(1000)
- // Verify the AI error message appears (canned response for 400 error)
await expect(
page
.getByRole('paragraph')
@@ -1445,7 +1291,6 @@ test('open search, Ask AI returns 400 error and shows general search results', a
),
).toBeVisible()
- // Verify general search results appear above the AI section
const searchResults = page.getByTestId('general-autocomplete-suggestions')
const aiSection = page.locator('#ask-ai-result-container')
@@ -1460,13 +1305,11 @@ test.describe('LandingCarousel component', () => {
const carousel = page.locator('[data-testid="landing-carousel"]')
await expect(carousel).toBeVisible()
- // Check that article cards are present. Brand Card renders each card's title
- // as an (Card.Heading) wrapping a stretched , so target the heading.
+ // Brand Card renders each card title as h3 Card.Heading around a stretched link.
const items = page.locator('[data-testid="carousel-items"]')
const cardHeadings = items.locator('h3')
await expect(cardHeadings.first()).toBeVisible()
- // Verify cards have real titles (not "Unknown Article" when article not found)
await expect(cardHeadings.first()).not.toHaveText('Unknown Article')
})
@@ -1477,15 +1320,13 @@ test.describe('LandingCarousel component', () => {
const carousel = page.locator('[data-testid="landing-carousel"]')
await expect(carousel).toBeVisible()
- // Should show 3 cards on desktop
const cards = carousel.locator('a')
await expect(cards).toHaveCount(3)
- // Check for navigation buttons if there are more than 3 articles
const nextButton = carousel.getByRole('button', { name: 'Next articles' })
if (await nextButton.isVisible()) {
const prevButton = carousel.getByRole('button', { name: 'Previous articles' })
- await expect(prevButton).toBeDisabled() // Should be disabled on first page
+ await expect(prevButton).toBeDisabled()
await expect(nextButton).toBeEnabled()
}
})
@@ -1497,7 +1338,6 @@ test.describe('LandingCarousel component', () => {
const carousel = page.locator('[data-testid="landing-carousel"]')
await expect(carousel).toBeVisible()
- // Should show 1 card on mobile
const cards = carousel.locator('a')
await expect(cards).toHaveCount(1)
})
@@ -1507,36 +1347,32 @@ test.describe('Multi-carousel support', () => {
test('displays multiple carousels from carousels frontmatter', async ({ page }) => {
await page.goto('/get-started/multi-carousel')
- // Should have multiple carousels rendered
const carousels = page.locator('[data-testid="landing-carousel"]')
const carouselCount = await carousels.count()
- // We defined exactly 2 carousels in the frontmatter
+ // Frontmatter defines exactly two carousels.
expect(carouselCount).toBe(2)
})
test('carousel with matching ui.yml key displays translated title', async ({ page }) => {
await page.goto('/get-started/multi-carousel')
- // The "recommended" carousel should show "Recommended" title from ui.yml
+ // The recommended carousel title comes from ui.yml.
const carouselHeadings = page.locator('[data-testid="landing-carousel"] h2')
const headingTexts = await carouselHeadings.allTextContents()
- // Check that at least one heading has "Recommended"
expect(headingTexts.some((text) => text.includes('Recommended'))).toBe(true)
})
test('carousel without matching ui.yml key renders without title', async ({ page }) => {
await page.goto('/get-started/multi-carousel')
- // The "titleTwoNoMatchingUiYml" carousel should not have a visible heading
- // or the heading element should be empty/not exist for that carousel
+ // A carousel without a matching ui.yml key has no heading element.
const carouselHeadings = page.locator('[data-testid="landing-carousel"] h2')
const headingTexts = await carouselHeadings.allTextContents()
- // The raw key "titleTwoNoMatchingUiYml" should NOT appear as a heading
- // (the component should not show the key as fallback)
+ // titleTwoNoMatchingUiYml must not render as a fallback heading.
expect(headingTexts.some((text) => text === 'titleTwoNoMatchingUiYml')).toBe(false)
})
@@ -1546,10 +1382,8 @@ test.describe('Multi-carousel support', () => {
const carousels = page.locator('[data-testid="landing-carousel"]')
const count = await carousels.count()
- // We have 2 carousels: "recommended" and "titleTwoNoMatchingUiYml"
expect(count).toBe(2)
- // Count carousels that have h2 elements
let carouselsWithHeadings = 0
for (let i = 0; i < count; i++) {
const carousel = carousels.nth(i)
@@ -1559,11 +1393,9 @@ test.describe('Multi-carousel support', () => {
}
}
- // Only 1 carousel should have a heading (recommended has ui.yml entry)
- // titleTwoNoMatchingUiYml should NOT have an h2 element at all
+ // Only recommended has a ui.yml entry, so titleTwoNoMatchingUiYml must not render an h2.
expect(carouselsWithHeadings).toBe(1)
- // Verify the specific titles that should be visible
const visibleHeadings = await carousels.locator('h2').allTextContents()
expect(visibleHeadings).toContain('Recommended')
expect(visibleHeadings).not.toContain('titleTwoNoMatchingUiYml')
@@ -1575,7 +1407,6 @@ test.describe('Multi-carousel support', () => {
const carousels = page.locator('[data-testid="landing-carousel"]')
const count = await carousels.count()
- // Each carousel should have at least one article
for (let i = 0; i < count; i++) {
const carousel = carousels.nth(i)
const articles = carousel.locator('[data-testid="carousel-items"] a')
@@ -1592,14 +1423,12 @@ test.describe('Journey Tracks', () => {
const journeyTracks = page.locator('[data-testid="journey-tracks"]')
await expect(journeyTracks).toBeVisible()
- // Check that at least one track is displayed
const tracks = page.locator('[data-testid="journey-track"]')
await expect(tracks.first()).toBeVisible()
- // Verify track has proper structure
const firstTrack = tracks.first()
- await expect(firstTrack.locator('h2')).toBeVisible() // Track title
- await expect(firstTrack.locator('p')).toBeVisible() // Track description
+ await expect(firstTrack.locator('h2')).toBeVisible()
+ await expect(firstTrack.locator('p')).toBeVisible()
})
test('track expansion and collapse functionality', async ({ page }) => {
@@ -1608,7 +1437,6 @@ test.describe('Journey Tracks', () => {
const firstTrack = page.locator('[data-testid="journey-track"]').first()
const expandButton = firstTrack.locator('summary')
- // Initially collapsed
const articlesList = firstTrack.locator('[data-testid="journey-articles"]')
await expect(articlesList).not.toBeVisible()
@@ -1630,7 +1458,6 @@ test.describe('Journey Tracks', () => {
await expandButton.click()
- // Click on first article
const firstArticle = firstTrack.locator('[data-testid="journey-articles"] li a').first()
await expect(firstArticle).toBeVisible()
@@ -1646,7 +1473,7 @@ test.describe('Journey Tracks', () => {
const expandButton = firstTrack.locator('summary')
await expandButton.click()
- // article links should preserve the language and version
+ // Article links preserve language and version.
const firstArticle = firstTrack.locator('[data-testid="journey-articles"] li a').first()
const href = await firstArticle.getAttribute('href')
@@ -1659,7 +1486,6 @@ test.describe('Journey Tracks', () => {
const tracks = page.locator('[data-testid="journey-track"]')
- // Check that liquid templates are rendered (no raw template syntax visible)
const trackContent = await tracks.first().textContent()
expect(trackContent).not.toContain('{{')
expect(trackContent).not.toContain('}}')
@@ -1670,21 +1496,18 @@ test.describe('Journey Tracks', () => {
test('renders the single-track journey landing path', async ({ page }) => {
await page.goto('/get-started/test-journey-single')
- // single-track pages use the simplified heading + guide list, not the numbered cards
+ // Single-track pages render the simplified heading and guide list instead of numbered cards.
const singleTrack = page.locator('[data-testid="journey-single-track"]')
await expect(singleTrack).toBeVisible()
await expect(page.locator('[data-testid="journey-tracks"]')).toHaveCount(0)
- // heading is present
await expect(singleTrack.locator('h2')).toBeVisible()
- // guide list renders its article links
const guides = singleTrack.locator('[data-testid="journey-articles"] li a')
await expect(guides.first()).toBeVisible()
expect(await guides.count()).toBeGreaterThan(0)
- // without a surrounding card, the list must sit flush with the heading
- // rather than picking up the card's inset
+ // Without a card, the guide list sits flush with the heading instead of inheriting inset.
const listPaddingLeft = await singleTrack
.locator('[data-testid="journey-articles"]')
.evaluate((el) => getComputedStyle(el).paddingLeft)
@@ -1692,21 +1515,14 @@ test.describe('Journey Tracks', () => {
})
test('journey navigation components show on article pages', async ({ page }) => {
- // go to an article that's part of a journey track
await page.goto('/get-started/start-your-journey/hello-world')
- // The journey footer "Up next" nav should be visible. (The Docs 2026 redesign
- // removed the sidebar journey card; next-step info now lives in the bottom
- // pager + the in-panel "Up next" section.)
+ // Journey next-step info shows in the bottom pager and the right-rail Up next section.
const journeyNav = page.locator('[data-testid="journey-track-nav"]')
await expect(journeyNav).toBeVisible()
})
- // Restores the coverage the Docs 2026 migration dropped along with the sidebar
- // journey card: `alternativeNextStep` and its AUTOTITLE resolution now render
- // in the right-rail "Up next" section instead. That section rides the drawer's
- // reveal breakpoint, so it needs a viewport inside the drawer range and a
- // fixture long enough to keep the bottom pager outside the viewport.
+ // A drawer-range viewport shows alternativeNextStep and AUTOTITLE in Up next; the long fixture hides the pager.
test('up next displays branching text when present', async ({ page }) => {
await page.setViewportSize({ width: 1440, height: 900 })
await page.goto('/get-started/foo/journey-test-article')
@@ -1716,7 +1532,7 @@ test.describe('Journey Tracks', () => {
const upNext = page.getByTestId('up-next')
await expect(upNext).toBeVisible()
- // Branching text should be rendered with its markdown link resolved
+ // Branching text renders after resolving its markdown link.
await expect(upNext).toContainText('Want to skip ahead?')
await expect(upNext).not.toContainText('AUTOTITLE')
@@ -1758,7 +1574,6 @@ test.describe('Journey Tracks', () => {
const journeyNav = page.locator('[data-testid="journey-track-nav"]')
await expect(journeyNav).toBeVisible()
- // Link should display the next track's title and go to its first article
const nextTrackLink = journeyNav.locator('a').filter({ hasText: 'Advanced topics' })
await expect(nextTrackLink).toBeVisible()
@@ -1768,9 +1583,7 @@ test.describe('Journey Tracks', () => {
})
test.describe('Docs 2026 in-article navigation', () => {
- // Below the drawer's reveal breakpoint the right-rail "In this article" panel
- // is hidden and the collapsed control in the secondary bar is the ONLY
- // mini-TOC — the common case for most readers — so it needs its own coverage.
+ // Below the drawer breakpoint, the secondary-bar mini-TOC is the only in-page control.
test('the collapsed "In this article" menu navigates below the drawer breakpoint', async ({
page,
}) => {
@@ -1780,7 +1593,6 @@ test.describe('Docs 2026 in-article navigation', () => {
const subBar = page.getByTestId('overview-subbar')
await expect(subBar).toBeVisible()
- // The full drawer must not also be showing at this width.
await expect(page.getByTestId('minitoc')).toBeHidden()
await subBar.getByRole('button').click()
@@ -1794,11 +1606,7 @@ test.describe('Docs 2026 in-article navigation', () => {
expect(page.url()).toContain(href)
})
- // Regression guard. Platform/tool-gated headings stay in the DOM with the
- // `hidden` attribute, so they measure as an all-zero rect. Before
- // useActiveSection filtered by the selection, such a heading always satisfied
- // the "scrolled past" threshold, so the collapsed control could end up
- // labelled with a section belonging to a platform the reader had not chosen.
+ // useActiveSection filters hidden platform/tool headings because they have zero rects.
test('the collapsed menu is never labelled with a hidden platform section', async ({ page }) => {
await page.setViewportSize({ width: 1100, height: 900 })
await page.goto('/get-started/liquid/platform-specific?platform=windows')
@@ -1808,7 +1616,6 @@ test.describe('Docs 2026 in-article navigation', () => {
await expect(trigger).toBeVisible()
await expect(trigger).not.toContainText('Macintosh')
- // Scroll past the first heading so an active section is actually resolved.
await page.mouse.wheel(0, 2000)
await expect(trigger).not.toContainText('Macintosh')
})
@@ -1818,8 +1625,6 @@ test.describe('LandingArticleGridWithFilter component', () => {
test('displays article grid with filter controls', async ({ page }) => {
await page.goto('/get-started/article-grid-discovery')
- // Check that the main components are visible, title, categories drop
- // down, search input.
const articleGrid = page.getByTestId('article-grid')
await expect(articleGrid).toBeVisible()
@@ -1842,14 +1647,11 @@ test.describe('LandingArticleGridWithFilter component', () => {
const articleGrid = page.getByTestId('article-grid')
await expect(articleGrid).toBeVisible()
- // Check that article cards are present and they have expected structure
- // by checking the first card.
const articleCards = articleGrid.getByTestId('article-card')
await expect(articleCards.first()).toBeVisible()
const firstCard = articleCards.first()
- // Brand Card renders the title as an (Card.Heading) wrapping a
- // stretched , and the intro as a Card.Description .
+ // Brand Card renders titles as h3 Card.Heading links and intros as Card.Description paragraphs.
const titleLink = firstCard.locator('h3 a')
await expect(titleLink).toBeVisible()
@@ -1858,8 +1660,6 @@ test.describe('LandingArticleGridWithFilter component', () => {
const introText = await intro.textContent()
expect(introText).toBeTruthy()
- // Card should have categories, title, and intro, just check the card has
- // some text
const cardText = await firstCard.textContent()
expect(cardText).toBeTruthy()
expect(cardText!.length).toBeGreaterThan(0)
@@ -1868,27 +1668,23 @@ test.describe('LandingArticleGridWithFilter component', () => {
test('category filtering works correctly', async ({ page }) => {
await page.goto('/get-started/article-grid-discovery')
- // Check that category dropdown button exists and is clickable
const categoryDropdown = page.getByRole('button').filter({ hasText: 'All categories' })
await expect(categoryDropdown).toBeVisible()
- // Initially should show all articles (4 total in our fixtures)
+ // The fixture starts with four articles.
const articleGrid = page.getByTestId('article-grid')
await expect(articleGrid).toBeVisible()
const allArticleCards = articleGrid.getByTestId('article-card')
await expect(allArticleCards).toHaveCount(4)
- // Click the dropdown and the 'Testing' category
await categoryDropdown.click()
const testingOption = page.getByText('Testing', { exact: true }).last()
await expect(testingOption).toBeVisible()
await testingOption.click()
- // After filtering by Testing category, should show only 1 article based
- // on our fixtures.
+ // Filtering by Testing leaves one fixture article.
await expect(allArticleCards).toHaveCount(1)
- // Verify the filtered article contains "Testing" somewhere in its markup
const remainingCard = allArticleCards.first()
await expect(remainingCard).toContainText('Testing')
})
@@ -1899,18 +1695,17 @@ test.describe('LandingArticleGridWithFilter component', () => {
const searchInput = page.getByPlaceholder('Search articles')
await expect(searchInput).toBeVisible()
- // Initially should show all articles (4 total in our fixtures)
+ // The fixture starts with four articles.
const articleGrid = page.getByTestId('article-grid')
await expect(articleGrid).toBeVisible()
const articleCards = articleGrid.getByTestId('article-card')
await expect(articleCards).toHaveCount(4)
- // Search for "Grid" - based on our fixtures, multiple articles should have "Grid" in their names
+ // Multiple fixture article names contain Grid.
await searchInput.fill('Grid')
await expect(articleCards.first()).toBeVisible()
- // Verify that the remaining articles contain "Grid" in their content
const remainingCount = await articleCards.count()
expect(remainingCount).toBeGreaterThan(0)
for (let i = 0; i < remainingCount; i++) {
@@ -1925,44 +1720,33 @@ test.describe('LandingArticleGridWithFilter component', () => {
const searchInput = page.getByPlaceholder('Search articles')
await expect(searchInput).toBeVisible()
- // Search for a term that definitely won't match any articles, should show
- // no article cards
await searchInput.fill('noSuchArticles')
const articleGrid = page.getByTestId('article-grid')
await expect(articleGrid).toBeVisible()
const articleCards = articleGrid.getByTestId('article-card')
await expect(articleCards).toHaveCount(0)
- // Should show "no articles found" message as well
const noResultsMessage = page.getByTestId('no-articles-message')
await expect(noResultsMessage).toBeVisible()
await expect(noResultsMessage).toHaveText('No articles found matching your criteria.')
})
test('responsive behavior on different screen sizes', async ({ page }) => {
- // Super basic test, just make sure the article grid is visible on
- // different viewports sizes
-
- // Test desktop view (3 columns)
await page.setViewportSize({ width: 1200, height: 800 })
await page.goto('/get-started/article-grid-discovery')
const articleGrid = page.getByTestId('article-grid')
await expect(articleGrid).toBeVisible()
- // Test tablet view (2 columns)
await page.setViewportSize({ width: 768, height: 1024 })
- await page.waitForTimeout(100) // Brief wait for responsive changes
+ await page.waitForTimeout(100)
await expect(articleGrid).toBeVisible()
- // Test mobile view (1 column)
await page.setViewportSize({ width: 375, height: 667 })
- await page.waitForTimeout(100) // Brief wait for responsive changes
+ await page.waitForTimeout(100)
await expect(articleGrid).toBeVisible()
})
test('works with bespoke landing page', async ({ page }) => {
- // Other grid tests use the discovery landing page, bespoke pages are
- // similar so just do a quick check.
await page.goto('/get-started/article-grid-bespoke')
const articleGrid = page.getByTestId('article-grid')
@@ -1970,10 +1754,7 @@ test.describe('LandingArticleGridWithFilter component', () => {
})
test('card is keyboard-navigable via Enter (client-side)', async ({ page }) => {
- // The brand Card renders a native stretched anchor; a synthetic click from
- // pressing Enter on that anchor must bubble to the card's onClick handler so
- // keyboard users get the same client-side SPA navigation as mouse users.
- // Guards against a regression if the click-intercept logic is refactored.
+ // Brand Card's stretched anchor must bubble keyboard clicks for client-side navigation.
await page.goto('/get-started/article-grid-discovery')
const articleGrid = page.getByTestId('article-grid')
@@ -1983,8 +1764,7 @@ test.describe('LandingArticleGridWithFilter component', () => {
const href = await firstCardLink.getAttribute('href')
expect(href).toBeTruthy()
- // Mark the current document so we can prove navigation was client-side
- // (no full page reload): a hard navigation would wipe this window property.
+ // A hard navigation would clear this window marker; client-side navigation preserves it.
await page.evaluate(() => {
;(window as unknown as { __spaMarker?: boolean }).__spaMarker = true
})
@@ -2000,20 +1780,16 @@ test.describe('LandingArticleGridWithFilter component', () => {
})
test('bespoke landing page does not show duplicate articles', async ({ page }) => {
- // The bespoke fixture lists individual articles AND their parent group
- // as children, which would cause duplicates without deduplication.
+ // Bespoke fixtures list articles and their parent group, so deduplication prevents duplicates.
await page.goto('/get-started/article-grid-bespoke')
const articleGrid = page.getByTestId('article-grid')
await expect(articleGrid).toBeVisible()
const articleCards = articleGrid.getByTestId('article-card')
- // There are 4 unique articles across grid-category-one (2) and grid-category-two (2).
- // Even though grid-article-one and grid-article-two are listed both individually
- // and as children of grid-category-one, they should appear only once each.
+ // Four unique articles remain after deduplicating grid-article-one and grid-article-two.
await expect(articleCards).toHaveCount(4)
- // Verify no duplicate titles by collecting all card titles
const titles: string[] = []
const count = await articleCards.count()
for (let i = 0; i < count; i++) {
@@ -2027,19 +1803,16 @@ test.describe('LandingArticleGridWithFilter component', () => {
test.describe('Non-child page resolution', () => {
test('category page with local children renders properly', async ({ page }) => {
- // The local-category has local children (local-article-one, local-article-two)
- // and an external article reference via children frontmatter
+ // local-category mixes local-article-one, local-article-two, and an external frontmatter child.
await page.goto('/get-started/non-child-resolution/local-category')
- // Should have a title
await expect(page).toHaveTitle(/Local category test/)
- // The page should load without errors and have main content
await expect(page.locator('main')).toBeVisible()
})
test('cross-product children page loads correctly', async ({ page }) => {
- // The articles-only fixture now uses /content/ prefix in children for cross-product paths
+ // The articles-only fixture prefixes cross-product children with /content/.
await page.goto('/get-started/non-child-resolution/articles-only')
await expect(page).toHaveTitle(/Cross-product children test/)
@@ -2047,7 +1820,7 @@ test.describe('Non-child page resolution', () => {
})
test('children-only page with /content/ path loads correctly', async ({ page }) => {
- // The children-only fixture uses /content/ prefix for cross-product paths
+ // The children-only fixture prefixes cross-product children with /content/.
await page.goto('/get-started/non-child-resolution/children-only')
await expect(page).toHaveTitle(/Children only test/)
@@ -2062,20 +1835,19 @@ test.describe('Non-child page resolution', () => {
})
test('versioned cross-product children - fpt shows only fpt article', async ({ page }) => {
- // In fpt version, only the only-fpt article should be available
+ // In fpt, only only-fpt is available.
await page.goto('/get-started/non-child-resolution/versioned-cross-product')
await expect(page).toHaveTitle(/Versioned cross-product test/)
await expect(page.locator('main')).toBeVisible()
- // Check TOC has the fpt-only article
const tocLinks = page.locator('[data-testid="table-of-contents"] a')
await expect(tocLinks).toHaveCount(1)
await expect(tocLinks.first()).toHaveAttribute('href', /only-fpt/)
})
test('versioned cross-product children - ghec shows ghec articles', async ({ page }) => {
- // In ghec version, only-ghec and only-ghec-and-ghes should be available
+ // In ghec, only-ghec and only-ghec-and-ghes are available.
await page.goto(
'/enterprise-cloud@latest/get-started/non-child-resolution/versioned-cross-product',
)
@@ -2083,58 +1855,46 @@ test.describe('Non-child page resolution', () => {
await expect(page).toHaveTitle(/Versioned cross-product test/)
await expect(page.locator('main')).toBeVisible()
- // Check TOC has ghec articles (only-ghec and only-ghec-and-ghes)
const tocLinks = page.locator('[data-testid="table-of-contents"] a')
await expect(tocLinks).toHaveCount(2)
})
test('cross-product children excluded from sidebar in Japanese translation', async ({ page }) => {
- // The Japanese translation should work with cross-product children
+ // Japanese translations work with cross-product children.
await page.goto('/ja/get-started/non-child-resolution')
- // Verify page loads correctly with Japanese site context
- // Note: The title may not be fully translated in test fixtures, but the page should render
+ // Fixture titles can be partly untranslated, but Japanese site context must render.
await expect(page).toHaveTitle(/GitHub Docs/)
await expect(page.locator('main')).toBeVisible()
-
- // Verify page loads correctly - the cross-product children don't prevent the page from working
- // The detailed sidebar filtering is tested by the survey test which verifies no duplicate entries
})
})
test.describe('copy as markdown button', () => {
- // The article-body fetch backing this button is served for this fixture page
- // (see src/fixtures/tests/api-article-body.ts), so the copy path succeeds.
+ // api-article-body.ts serves this fixture's article-body fetch, so the copy path succeeds.
const articlePath = '/en/get-started/start-your-journey/api-article-body-test-page'
test('shows a checkmark after a successful copy', async ({ page, context }) => {
- // The click handler writes the article markdown to the clipboard.
await context.grantPermissions(['clipboard-read', 'clipboard-write'])
await page.goto(articlePath)
await turnOffExperimentsInPage(page)
- // `exact` matters: accessible-name matching is substring-based, so a bare
- // 'Copy markdown' also matches the code-block copy buttons that articles
- // with a ```markdown fence render ('Copy Markdown code to clipboard').
+ // Accessible-name matching treats names as substrings, so exact avoids code-block copy buttons.
const copyButton = page.getByRole('button', { name: 'Copy markdown', exact: true })
await expect(copyButton).toHaveCount(1)
await expect(copyButton).toBeVisible()
- // At rest the button is text-only — no icon at all. The checkmark below is
- // purely the success state.
+ // At rest the button is text-only; the checkmark is only the success state.
await expect(copyButton.locator('svg')).toHaveCount(0)
await copyButton.click()
- // After a successful copy, a checkmark appears...
await expect(copyButton.locator('.octicon-check')).toBeVisible()
- // ...and the article markdown lands on the clipboard.
const clipboardText = await page.evaluate(() => navigator.clipboard.readText())
expect(clipboardText).toContain('About GitHub')
- // The checkmark is temporary and clears again (2s timeout).
+ // The success checkmark clears after the 2s timeout.
await expect(copyButton.locator('.octicon-check')).toHaveCount(0, { timeout: 5000 })
})
})
diff --git a/src/frame/middleware/README.md b/src/frame/middleware/README.md
index e3f8c2b279f3..63e5e757e193 100644
--- a/src/frame/middleware/README.md
+++ b/src/frame/middleware/README.md
@@ -3,3 +3,15 @@
Each file in this directory exports an Express Middleware function.
For more info, see https://expressjs.com/en/guide/using-middleware.html
+
+## Mock Virtual Assistant portal
+
+`mock-va-portal.ts` lets you test the Virtual Assistant integration without access to a staging portal. The production portal rejects `localhost:4000` because it is hardened to `https://docs.github.com`.
+
+To test locally:
+
+1. Add `SUPPORT_PORTAL_URL=http://localhost:4000` to your `.env` file.
+2. Run `npm run dev`.
+3. Navigate to a page listed in the `PagePathToVaFlowMapping` object in `ArticleContext`.
+
+This mock is not secure. Use it only for local development.
diff --git a/src/frame/middleware/abort.ts b/src/frame/middleware/abort.ts
index e9f9496578ed..0e98af463e1a 100644
--- a/src/frame/middleware/abort.ts
+++ b/src/frame/middleware/abort.ts
@@ -14,18 +14,14 @@ class AbortError extends Error {
}
export default function abort(req: ExtendedRequest, res: Response, next: NextFunction) {
- // If the client aborts the connection, send an error
req.once('aborted', () => {
- // ignore aborts from next, usually has to do with webpack-hmr
+ // Ignore _next aborts, which usually come from webpack HMR.
if (req.path.startsWith('/_next')) {
return
}
- // NOTE: Node.js will also automatically set `req.aborted = true`
const incrementTags = []
- // Be careful with depending on attributes set on the `req` because
- // under certain conditions the contextualizers might not yet have
- // had a chance to run.
+ // Request contextualizers might not run before an abort, so guard optional request fields.
if (req.pagePath) {
incrementTags.push(`path:${req.pagePath}`)
}
diff --git a/src/frame/middleware/api.ts b/src/frame/middleware/api.ts
index a7c3f1acb7ac..4eef5c90a193 100644
--- a/src/frame/middleware/api.ts
+++ b/src/frame/middleware/api.ts
@@ -23,12 +23,8 @@ router.use('/anchor-redirect', anchorRedirect)
router.use('/pagelist', pageList)
router.use('/article', article)
-// The purpose of this is for convenience to everyone who runs this code
-// base locally but don't have an Elasticsearch server locally.
-// In production, this env var is always set but perhaps in a writer's
-// local laptop, they don't have an Elasticsearch. Neither a running local
-// server or the known credentials to a remote Elasticsearch. Whenever
-// that's the case, they can just HTTP proxy to the production server.
+// Local development proxies AI Search to docs.github.com when CSE_COPILOT_ENDPOINT
+// is unset, so writers do not need a local AI Search service.
if (process.env.CSE_COPILOT_ENDPOINT || process.env.NODE_ENV === 'test') {
router.use('/ai-search', aiSearch)
} else {
@@ -52,9 +48,8 @@ if (process.env.ELASTICSEARCH_URL) {
)
}
-// We need access to specific httpOnly cookies set on github.com from the client
-// The only way to access these on the client is to fetch them from the server
-// Limit this endpoint to 1req/min because a client should only call this route once
+// Browser JavaScript cannot read github.com httpOnly cookies.
+// The server endpoint returns the staff flag that client code needs.
router.get('/cookies', (req, res) => {
noCacheControl(res)
const cookies = {
diff --git a/src/frame/middleware/block-robots.ts b/src/frame/middleware/block-robots.ts
index 298575ec9f0c..c49e8f602f98 100644
--- a/src/frame/middleware/block-robots.ts
+++ b/src/frame/middleware/block-robots.ts
@@ -4,7 +4,7 @@ import { productMap } from '@/products/lib/all-products'
import { deprecated } from '@/versions/lib/enterprise-server-releases'
const pathRegExps: RegExp[] = [
- // Disallow indexing of WIP products
+ // WIP and hidden products stay out of search indexes.
...Object.values(productMap)
.filter((product) => product.wip || product.hidden)
.map((product) => [
@@ -12,7 +12,7 @@ const pathRegExps: RegExp[] = [
...product.versions!.map((version) => new RegExp(`^/.*?${version}/${product.id}`, 'i')),
]),
- // Disallow indexing of deprecated enterprise versions
+ // Deprecated enterprise versions stay out of search indexes.
...deprecated.map((version) => [
new RegExp(`^/.*?/enterprise-server@${version}/.*?`, 'i'),
new RegExp(`^/.*?/enterprise/${version}/.*?`, 'i'),
diff --git a/src/frame/middleware/cache-control.ts b/src/frame/middleware/cache-control.ts
index b53e5ca98364..c529f64f7918 100644
--- a/src/frame/middleware/cache-control.ts
+++ b/src/frame/middleware/cache-control.ts
@@ -19,9 +19,8 @@ const ONE_DAY = 24 * ONE_HOUR
const ONE_WEEK = 7 * ONE_DAY
const ONE_YEAR = 365 * ONE_DAY
-// Return a function you can pass a Response object to and it will set the `Cache-Control` header.
-// Max age is in seconds.
-// Max age should not be greater than 31536000, per .
+// maxAge is seconds. Keep it at or below 31536000.
+// https://www.ietf.org/rfc/rfc2616.txt
function cacheControlFactory(
maxAge: number = 0,
{
@@ -53,16 +52,14 @@ function cacheControlFactory(
}
}
-// The rest of this file is roughly in order from shortest max age to longest.
-
-// If you do not want caching.
export const noCacheControl = cacheControlFactory(0)
-// Short cache for 4xx errors.
+// 4xx errors get a short cache.
export const errorCacheControl = cacheControlFactory(ONE_MINUTE)
-// For default cache control, up to one week in cache but much shorter in browser.
-// Most responses are under the default cache control policy.
+// Default responses cache for 1 minute in browsers and 10 minutes in the CDN.
+// The CDN can serve stale responses for 1 week while revalidating or on errors.
+// Most responses use this policy.
const browserCacheControl = cacheControlFactory(ONE_MINUTE)
const defaultCDNCacheControl = cacheControlFactory(TEN_MINUTES, {
key: 'surrogate-control',
@@ -75,30 +72,29 @@ export function defaultCacheControl(res: Response): void {
}
export const searchCacheControl = defaultCacheControl
-// For requests where the response can vary between a HTML and Markdown response
-// using the accept header.
+// The Accept header can switch content responses between HTML and Markdown.
export function contentTypeCacheControl(res: Response): void {
defaultCacheControl(res)
res.append('vary', 'accept')
}
-// Vary on language when needed.
-// `x-user-language` is a custom request header derived from `req.cookie:user_language`.
-// `accept-language` is truncated to one of our available languages.
+// Vary by accept-language and x-user-language.
+// x-user-language comes from req.cookie:user_language.
+// Upstream code truncates accept-language to available languages.
// https://bit.ly/3u5UeRN
export function languageCacheControl(res: Response): void {
defaultCacheControl(res)
res.append('vary', 'accept-language, x-user-language')
}
-// Vary on both language and version for homepage redirects.
-// `x-user-version` is a custom request header derived from `req.cookie:user_version`.
+// Homepage redirects also vary by x-user-version.
+// x-user-version comes from req.cookie:user_version.
export function languageAndVersionCacheControl(res: Response): void {
defaultCacheControl(res)
res.append('vary', 'accept-language, x-user-language, x-user-version')
}
-// Long cache control for versioned assets: such as images, CSS, prebuilt JS.
+// Versioned images, CSS, and prebuilt JS use long browser and CDN caches.
const assetBrowserCacheControl = cacheControlFactory(TEN_MINUTES)
const assetCDNCacheControl = cacheControlFactory(ONE_WEEK, {
key: 'surrogate-control',
@@ -111,7 +107,7 @@ export function assetCacheControl(res: Response): void {
assetCDNCacheControl(res)
}
-// Long caching for archived pages and assets.
+// Archived pages and assets use long browser and CDN caches.
const archivedBrowserCacheControl = cacheControlFactory(TEN_MINUTES)
const archivedCDNCacheControl = cacheControlFactory(ONE_YEAR, {
key: 'surrogate-control',
diff --git a/src/frame/middleware/categories-for-support.ts b/src/frame/middleware/categories-for-support.ts
index ad8bae698a57..bf1bac8f945f 100644
--- a/src/frame/middleware/categories-for-support.ts
+++ b/src/frame/middleware/categories-for-support.ts
@@ -14,8 +14,7 @@ type Category = {
published_articles: Article[]
}
-// This middleware exposes a list of all categories and child articles at /categories.json.
-// GitHub Support uses this for internal ZenDesk search functionality.
+// /categories.json gives GitHub Support categories and child articles for Zendesk search.
export default async function categoriesForSupport(req: ExtendedRequest, res: Response) {
const englishSiteTree = req.context!.siteTree!.en
const allCategories: Category[] = []
@@ -26,9 +25,7 @@ export default async function categoriesForSupport(req: ExtendedRequest, res: Re
if (!productPage.childPages || !productPage.childPages.length) continue
await Promise.all(
productPage.childPages.map(async (categoryPage) => {
- // We can't get the rendered titles from middleware/render-tree-titles
- // here because that middleware only runs on the current version, and this
- // middleware processes all versions.
+ // Site-tree titles are raw, so render any that contain Liquid.
if (!req.context) return
const name = categoryPage.page.title.includes('{')
? await categoryPage.page.renderProp('title', req.context, renderOpts)
@@ -42,8 +39,7 @@ export default async function categoriesForSupport(req: ExtendedRequest, res: Re
)
}
- // Cache somewhat aggressively but note that it will be soft-purged
- // in every prod deployment.
+ // Use the default browser and CDN cache policy.
defaultCacheControl(res)
return res.json(allCategories)
@@ -67,7 +63,6 @@ async function findArticlesPerCategory(
if (!currentPage.childPages) return articlesArray
- // Run recursively to find any articles deeper in the tree.
await Promise.all(
currentPage.childPages.map(async (childPage) => {
await findArticlesPerCategory(childPage, articlesArray, context)
diff --git a/src/frame/middleware/context/breadcrumbs.ts b/src/frame/middleware/context/breadcrumbs.ts
index 9f5beba950dd..b6cbca12c224 100644
--- a/src/frame/middleware/context/breadcrumbs.ts
+++ b/src/frame/middleware/context/breadcrumbs.ts
@@ -10,7 +10,6 @@ export default function breadcrumbs(req: ExtendedRequest, res: Response, next: N
req.context.breadcrumbs = []
- // Return an empty array on the landing page.
if (req.context.page.documentType === 'homepage') {
return next()
}
@@ -22,21 +21,15 @@ export default function breadcrumbs(req: ExtendedRequest, res: Response, next: N
const earlyAccessExceptions = ['insights', 'enterprise-importer']
+// For Early Access pages, getBreadcrumbs omits /early-access and the product segment.
+// For example, /en/early-access/github/migrating starts at /migrating.
function getBreadcrumbs(req: ExtendedRequest, isEarlyAccess: boolean) {
if (!req.context || !req.context.currentPath || !req.context.currentProductTreeTitles)
throw new Error('request is not contextualized')
let cutoff = 0
- // When in Early access docs consider the "root" be much higher.
- // E.g. /en/early-access/github/migrating/understanding/about
- // we only want it start at /migrating/understanding/about
- // Essentially, we're skipping "/early-access" and its first
- // top-level like "/github"
if (isEarlyAccess) {
const split = req.context.currentPath!.split('/')
- // There are a few exceptions to this rule for the
- // /{version}/early-access//... URLs because they're a
- // bit different.
- // If there are more known exceptions, add them to the array above.
+ // insights and enterprise-importer Early Access URLs keep their product segment.
if (earlyAccessExceptions.some((product) => split.includes(product))) {
cutoff = 1
} else {
@@ -55,22 +48,7 @@ function getBreadcrumbs(req: ExtendedRequest, isEarlyAccess: boolean) {
return breadcrumbsResult
}
-// Return an array as if you'd traverse down a tree. Imagine a tree like
-//
-// (root /)
-// / \
-// (/foo) (/bar)
-// / \
-// (/foo/bar) (/foo/buzz)
-//
-// If the "currentPath" is `/foo/buzz` what you want to return is:
-//
-// [
-// {href: /, title: TITLE},
-// {href: /foo, title: TITLE}
-// {href: /foo/buzz, title: TITLE}
-// ]
-//
+// Example: /en/actions/learn-github-actions returns each matching ancestor and that page.
function traverseTreeTitles(currentPath: string | string[], tree: TitlesTree) {
const { href, title, shortTitle } = tree
const crumbs = [
@@ -85,17 +63,13 @@ function traverseTreeTitles(currentPath: string | string[], tree: TitlesTree) {
for (const child of tree.childPages) {
if (isParentOrEqualArray(child.href.split('/'), currentPathSplit)) {
crumbs.push(...traverseTreeTitles(currentPathSplit, child))
- // Only ever going down 1 of the children
break
}
}
return crumbs
}
-// Return true if an array is part of another array or equal.
-// Like `/foo/bar` is part of `/foo/bar/buzz`.
-// But also include `/foo/bar/buzz`.
-// Don't include `/foo/ba` if the final path is `/foo/baring`.
+// Compare split paths so /foo/ba does not match /foo/baring.
function isParentOrEqualArray(base: string[], final: string[]) {
return base.every((part, i) => part === final[i])
}
diff --git a/src/frame/middleware/context/context.ts b/src/frame/middleware/context/context.ts
index 7d0e0390b1da..b3dd70c75c50 100644
--- a/src/frame/middleware/context/context.ts
+++ b/src/frame/middleware/context/context.ts
@@ -19,19 +19,20 @@ import nonEnterpriseDefaultVersion from '@/versions/lib/non-enterprise-default-v
import { getDataByLanguage, getUIDataMerged } from '@/data-directory/lib/get-data'
import { updateLoggerContext } from '@/observability/logger/lib/logger-context'
-// This doesn't change just because the request changes, so compute it once.
+// Enterprise Server version keys do not depend on each request, so compute them once.
const enterpriseServerVersions = Object.keys(allVersions).filter((version) =>
version.startsWith('enterprise-server@'),
)
-// Supply all route handlers with a baseline `req.context` object
-// Note that additional middleware in middleware/index.ts adds to this context object
+// middleware/index.ts depends on contextualize setting baseline req.context.
+// For non-English pages, contextualize adds getEnglishPage for renderContentWithFallback.
+// It handles fallback-eligible Liquid, autotitle, and empty-title errors.
export default async function contextualize(
req: ExtendedRequest,
res: Response,
next: NextFunction,
) {
- // Ensure that we load some data only once on first request
+ // warmServer caches this data after the first request.
const { redirects, siteTree, pages: pageMap } = await warmServer([])
const context: Context = {}
@@ -40,17 +41,14 @@ export default async function contextualize(
req.context.process = { env: {} }
if (req.pagePath && req.pagePath.endsWith('.md')) {
- // req.pagePath is used later in the rendering pipeline to
- // locate the file in the tree so it cannot have .md
+ // The rendering pipeline resolves req.pagePath in the tree without the .md suffix.
req.pagePath = req.pagePath.replace(/\/index\.md$/, '').replace(/\.md$/, '')
req.context.markdownRequested = true
- // Track that markdown was requested via URL suffix, not Accept header.
- // This avoids adding a misleading Vary: accept cache header.
+ // markdownViaUrl avoids a misleading Vary: accept header for URL suffix requests.
req.context.markdownViaUrl = true
}
- // define each context property explicitly for code-search friendliness
- // e.g. searches for "req.context.page" will include results from this file
+ // Explicit req.context property assignments keep code search results discoverable.
req.context.currentLanguage = req.language
req.context.userLanguage = req.userLanguage
req.context.currentVersion = getVersionStringFromPath(req.pagePath) as string
@@ -62,8 +60,7 @@ export default async function contextualize(
req.context.allVersions = allVersions
req.context.currentPathWithoutLanguage = getPathWithoutLanguage(req.pagePath)
- // define property for writers to link to the current page in a different version
- // includes any type of rendered page not just "articles"
+ // currentArticle lets writers link any rendered page, not only articles, in another version.
req.context.currentArticle = getPathWithoutVersion(req.context.currentPathWithoutLanguage)
req.context.currentPath = req.pagePath
req.context.query = req.query
@@ -83,20 +80,15 @@ export default async function contextualize(
req.context.nonEnterpriseDefaultVersion = nonEnterpriseDefaultVersion
req.context.initialRestVersioningReleaseDate =
allVersions[nonEnterpriseDefaultVersion].apiVersions[0]
- // The default REST API version that requests use when no X-GitHub-Api-Version header is specified
- // This is the oldest supported version (last in the sorted descending array)
+ // apiVersions sorts newest first, so the last item is the default without X-GitHub-Api-Version.
const apiVersions = allVersions[nonEnterpriseDefaultVersion].apiVersions
req.context.defaultRestApiVersion = apiVersions[apiVersions.length - 1]
const restDate = new Date(req.context.initialRestVersioningReleaseDate)
req.context.initialRestVersioningReleaseDateLong = restDate.toUTCString().split(' 00:')[0]
- // Non-English pages need this so that `Page.render`, when it calls
- // `renderContentWithFallback`, can fall back to the English content when the
- // translation hits a fallback-eligible error (Liquid, autotitle, empty title).
if (req.language !== 'en') {
- // This is a function so the lookup only happens when a translated page
- // actually needs to fall back. Most requests never need it.
+ // getEnglishPage delays the lookup until a translated page needs fallback content.
req.context.getEnglishPage = (ctx) => {
if (!ctx.enPage) {
const { page } = ctx
diff --git a/src/frame/middleware/context/current-product-tree.ts b/src/frame/middleware/context/current-product-tree.ts
index 1a34c3015c83..c99b741c3b23 100644
--- a/src/frame/middleware/context/current-product-tree.ts
+++ b/src/frame/middleware/context/current-product-tree.ts
@@ -8,7 +8,6 @@ import findPageInSiteTree from '@/frame/lib/find-page-in-site-tree'
import removeFPTFromPath from '@/versions/lib/remove-fpt-from-path'
import { executeWithFallback } from '@/languages/lib/render-with-fallback'
-// This module adds currentProductTree to the context object for use in layouts.
export default async function currentProductTree(
req: ExtendedRequest,
res: Response,
@@ -18,7 +17,7 @@ export default async function currentProductTree(
if (!req.context.page) return next()
if (req.context.page.documentType === 'homepage') return next()
- // We need this so we can fall back to English if localized pages are out of sync.
+ // Keep the English tree available because localized pages can lag behind it.
if (!req.context.siteTree) throw new Error('siteTree is required')
if (!req.context.currentVersion) throw new Error('currentVersion is required')
req.context.currentEnglishTree = req.context.siteTree.en[req.context.currentVersion]
@@ -41,22 +40,17 @@ export default async function currentProductTree(
currentProductPath,
)
- // First make a slim tree of just the 'href', 'title', 'shortTitle'
- // 'documentType' and 'childPages' (which is recursive).
- // This gets used for subcategory and category pages.
+ // currentProductTreeTitles keeps href, title, shortTitle, documentType, and childPages.
req.context.currentProductTreeTitles = await getCurrentProductTreeTitles(
req.context.currentProductTree,
req.context,
)
- // Now make an even slimmer version that excludes all hidden pages.
- // This is used for sidebars.
+ // Sidebar data excludes hidden pages.
req.context.currentProductTreeTitlesExcludeHidden = excludeHidden(
req.context.currentProductTreeTitles,
)
- // Some pages, like hidden pages, don't have a tree. For example,
- // the search page. That one uses the same items as the homepage
- // for its sidebar.
+ // Hidden pages leave sidebarTree unset because excludeHidden returns null for the root.
if (req.context.currentProductTreeTitlesExcludeHidden) {
req.context.sidebarTree = sidebarTree(req.context.currentProductTreeTitlesExcludeHidden)
}
@@ -64,35 +58,18 @@ export default async function currentProductTree(
return next()
}
-// Return a nested object that contains the bits and pieces we need
-// for the tree which is used for sidebars and listing
async function getCurrentProductTreeTitles(input: Tree, context: Context): Promise {
const { page, href } = input
const childPages = await Promise.all(
(input.childPages || []).map((child) => getCurrentProductTreeTitles(child, context)),
)
- // If the current page is a translation we're going to need the English
- // equivalent for multiple things later in this function.
+ // Translated pages need their English page for fallback rendering and short-title comparison.
const enPage =
page.languageCode !== 'en' ? context.pages![href.replace(`/${page.languageCode}`, '/en')] : null
- let rawShortTitle = page.rawShortTitle // might change our minds about this
- // A lot of translations have a short title that is identical to the
- // English equivalent. E.g.
- //
- // content/foo.md:
- //
- // title: Something Something Bla
- // shortTitle: Something
- //
- // translations/docs-internal.se-sv/content/foo.md:
- //
- // title: Nånting Nånting Blä
- // shortTitle: Something
- //
- // I.e. the translations `shortTitle` hasn't been translated.
- // If this is the case, use the long title instead.
+ let rawShortTitle = page.rawShortTitle
+ // Swaps in rawTitle when shortTitle matches English, but the render below reads page.rawShortTitle.
if (page.languageCode !== 'en' && page.rawShortTitle) {
if (page.rawShortTitle === enPage!.shortTitle) {
rawShortTitle = page.rawTitle
@@ -112,8 +89,7 @@ async function getCurrentProductTreeTitles(input: Tree, context: Context): Promi
)
}
- // If the short title was present but "useless" (same as the title),
- // force it to be an empty string to not waste space.
+ // Empty duplicate short titles to avoid wasting sidebar space.
const shortTitle =
renderedShortTitle && (renderedShortTitle || '') !== renderedFullTitle ? renderedShortTitle : ''
@@ -148,12 +124,10 @@ function excludeHidden(tree: TitlesTree) {
function sidebarTree(tree: TitlesTree) {
const { href, title, shortTitle, childPages, sidebarLink } = tree
- // Filter out cross-product children from the sidebar
+ // Sidebars show only children from the current product.
const filteredChildPages = childPages.filter((child) => !child.crossProductChild)
- // Filter out children that are descendants of another sibling.
- // When a page lists both a subdirectory and individual articles from it,
- // the articles should only appear nested under the subdirectory in the sidebar.
+ // If siblings include a subdirectory and its articles, nest the articles under the subdirectory.
const siblingHrefs = filteredChildPages.map((c) => c.href)
const dedupedChildPages = filteredChildPages.filter(
(child) => !siblingHrefs.some((sh) => sh !== child.href && child.href.startsWith(`${sh}/`)),
diff --git a/src/frame/middleware/context/generic-toc.ts b/src/frame/middleware/context/generic-toc.ts
index 93a57bf99f91..67012fe6c363 100644
--- a/src/frame/middleware/context/generic-toc.ts
+++ b/src/frame/middleware/context/generic-toc.ts
@@ -12,9 +12,7 @@ function isNewLandingPage(currentLayoutName: string): boolean {
)
}
-// This module adds either flatTocItems or nestedTocItems to the context object for
-// product, category, and subcategory TOCs that don't have other layouts specified.
-// They are rendered by includes/generic-toc-flat.html or includes/generic-toc-nested.html.
+// genericToc assigns genericTocFlat or genericTocNested for React landing contexts.
export default async function genericToc(req: ExtendedRequest, res: Response, next: NextFunction) {
if (!req.context) throw new Error('request not contextualized')
if (!req.context.page) return next()
@@ -23,7 +21,7 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
!isNewLandingPage(req.context.currentLayoutName || '')
)
return next()
- // This middleware can only run on product, category, and subcategories.
+ // TOC layouts skip homepages, articles, and search.
if (
req.context.page.documentType === 'homepage' ||
req.context.page.documentType === 'article' ||
@@ -39,8 +37,7 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
subcategory: 'flat',
}
- // Frontmatter can optionally be set on an Early Access product to show hidden child items.
- // If so, this is a special case where we want to override the flat tocType and use a nested type.
+ // earlyAccessToc frontmatter exposes hidden child items by switching products to nested TOCs.
const earlyAccessToc = req.context.page.earlyAccessToc
if (!req.context.currentProductTree) throw new Error('currentProductTree not in context')
@@ -53,10 +50,7 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
req.pagePath,
)
- // The intent is that a category whose children have no children of their own
- // should render like a subcategory. It doesn't work: `child.children` is `[]`
- // for leaf pages and `[]` is truthy, so `hasGrandchildren` is true for any
- // category with children at all. This probably wants `child.children?.length`.
+ // fauxSubcategory is meant to flatten categories without grandchildren, but [] is truthy.
let fauxSubcategory = false
if (req.context.page.documentType === 'category' && req.context.page.autogenerated !== 'rest') {
const hasGrandchildren = (treePage.childPages || []).some((child) => child.children)
@@ -69,10 +63,7 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
? 'flat'
: tocTypes[req.context.page.documentType]
- // By default, only include hidden child items on a TOC page if it's an Early Access category or
- // subcategory page, not a product or 'articles' fake category page (e.g., /early-access/github/articles).
- // This is because we don't want entire EA product TOCs to be publicly browseable, but anything at the category
- // or below level is fair game because that content is scoped to specific features.
+ // By default, Early Access category and subcategory TOCs expose hidden children except /articles.
const isCategoryOrSubcategory =
req.context.page.documentType === 'category' || req.context.page.documentType === 'subcategory'
if (!req.context.currentPath) throw new Error('currentPath not in context')
@@ -85,7 +76,6 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
let isRecursive
let renderIntros
- // Get an array of child links with intros and add it to the context object.
if (currentTocType === 'flat' && !isOneOffProductToc) {
isRecursive = false
renderIntros = true
@@ -97,7 +87,6 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
})
}
- // Get an array of child subcategories and their child articles and add it to the context object.
if (currentTocType === 'nested' || isOneOffProductToc) {
isRecursive = !isOneOffProductToc
renderIntros = false
@@ -119,8 +108,9 @@ type Options = {
textOnly: boolean
}
+// rawIntro can contain Markdown without Liquid, so renderProp still needs to process it.
+// Generic TOC components keep intro HTML unless a landing-page layout needs text only.
async function getTocItems(node: Tree, context: Context, opts: Options): Promise {
- // Cleaner than trying to be too terse inside the `.filter()` inline callback.
function filterHidden(child: Tree): boolean {
return opts.includeHidden || !child.page.hidden
}
@@ -138,11 +128,6 @@ async function getTocItems(node: Tree, context: Context, opts: Options): Promise
if (opts.renderIntros) {
intro = ''
if (page.rawIntro) {
- // The intro can contain Markdown even though it might not
- // contain any Liquid.
- // Use textOnly for new landing pages to strip HTML tags.
- // For other pages, we intend to display the intro in a table of contents
- // component with the HTML (dangerouslySetInnerHTML).
intro = await page.renderProp(
'rawIntro',
context,
diff --git a/src/frame/middleware/context/glossaries.ts b/src/frame/middleware/context/glossaries.ts
index 8d49f6a815e2..8b7c81cef50c 100644
--- a/src/frame/middleware/context/glossaries.ts
+++ b/src/frame/middleware/context/glossaries.ts
@@ -12,18 +12,11 @@ export default async function glossaries(req: ExtendedRequest, res: Response, ne
if (!req.context) throw new Error('request is not contextualized')
- // If the current version (which is found as part of the URL), does not
- // correspond to a supported version, the Liquid rendering will fail
- // (if there's uses of `ifversion` in any the Liquid).
- // So we'll skip this contextualizer and let the 404 error take over later.
+ // Skip unsupported versions so ifversion Liquid errors do not replace the later 404.
if (!req.context.currentVersionObj) return next()
- // When the current language is *not* English, we'll need to get the English
- // glossary based on the term. We'll use this to render the translated
- // glossaries. For example, if the Korean translation has a corruption
- // in its description we need to know the English equivalent.
+ // Translated glossaries need English descriptions to repair corrupted Liquid before rendering.
const enGlossaryMap = new Map()
- // But we don't need to bother if the current language is English.
if (req.context.currentLanguage !== 'en') {
const enGlossariesRaw: Glossary[] = getDataByLanguage('glossaries.external', 'en') as Glossary[]
@@ -32,11 +25,7 @@ export default async function glossaries(req: ExtendedRequest, res: Response, ne
}
}
- // The glossaries Yaml file contains descriptions that might contain
- // Liquid. They need to be rendered out.
- // The github-glossary.md file uses Liquid to generate the Markdown.
- // It uses Liquid to say `{{ glossary.description }}` but once that's
- // injected there it needs to have its own possible Liquid rendered out.
+ // github-glossary.md injects glossary descriptions before their Liquid renders.
const glossariesRaw: Glossary[] = getDataByLanguage(
'glossaries.external',
req.context.currentLanguage!,
@@ -48,13 +37,7 @@ export default async function glossaries(req: ExtendedRequest, res: Response, ne
if (req.context!.currentLanguage !== 'en') {
description = correctTranslatedContentStrings(
description,
- // The function needs the English equivalent of the translated
- // Markdown. It's to make possible corrections to the
- // translation's Liquid which might have lost important
- // linebreaks.
- // But because the terms themselves are often translated,
- // in this mapping we often don't have an English equivalent.
- // So that's why we fall back on the empty string.
+ // English Markdown repairs Liquid line breaks; some translated terms lack matches.
enGlossaryMap.get(glossary.term) || '',
{ code: req.context!.currentLanguage },
)
@@ -64,17 +47,13 @@ export default async function glossaries(req: ExtendedRequest, res: Response, ne
() => liquid.parseAndRender(description, req.context),
(enContext: Context) => {
const { term } = glossary
- // It *could* be that the translation is referring to a term
- // that no longer exists in the English glossary. In that case,
- // simply skip this term.
+ // Skip translated terms missing from the English glossary.
if (!enGlossaryMap.has(term)) return
const enDescription = enGlossaryMap.get(term)
return liquid.parseAndRender(enDescription, enContext)
},
)
- // It's important to use `Object.assign` here to avoid mutating the
- // original object because from `getDataByLanguage`, reads from an
- // in-memory cache so if we mutated it, it would be mutated for all.
+ // Object.assign preserves the getDataByLanguage cache object shared across requests.
return Object.assign({}, glossary, { description })
}),
)
diff --git a/src/frame/middleware/context/layout.ts b/src/frame/middleware/context/layout.ts
index 447955cc8917..45f3a5342c84 100644
--- a/src/frame/middleware/context/layout.ts
+++ b/src/frame/middleware/context/layout.ts
@@ -9,7 +9,7 @@ export default function layoutContext(req: ExtendedRequest, res: Response, next:
let layoutName = 'default'
if (req.context.page.layout) {
if (typeof req.context.page.layout === 'boolean') {
- // A `layout: false` value means use no layout.
+ // Only layout: true reaches here and clears the layout name. layout: false gets the default.
layoutName = ''
} else if (typeof req.context.page.layout === 'string') {
layoutName = req.context.page.layout
diff --git a/src/frame/middleware/context/product-groups.ts b/src/frame/middleware/context/product-groups.ts
index 6a9427277394..b875c711d5b4 100644
--- a/src/frame/middleware/context/product-groups.ts
+++ b/src/frame/middleware/context/product-groups.ts
@@ -8,18 +8,20 @@ import { allVersionKeys } from '@/versions/lib/all-versions'
const isHomepage = (path: string) => {
const split = path.split('/')
- // E.g. `/foo` but not `foo/bar` or `foo/`
+ // Matches /en but not en/foo or /en/.
if (split.length === 2 && split[1] && !split[0]) {
return languageKeys.includes(split[1])
}
- // E.g. `/foo/possiblyproductname` but not `foo/possiblyproductname` or
- // `/foo/something/`
+ // Matches /en/free-pro-team@latest but not en/free-pro-team@latest or /en/actions/.
if (split.length === 3 && !split[0] && split[2]) {
return allVersionKeys.includes(split[2])
}
return false
}
+// handleNextDataPath maps Next data URLs, such as /_next/data/development/en/actions.json,
+// to normal page paths, so productGroups reads req.pagePath.
+// It requires a valid currentVersionObj because ifversion Liquid in getProductGroups throws otherwise.
export default async function productGroups(
req: ExtendedRequest,
res: Response,
@@ -28,18 +30,6 @@ export default async function productGroups(
if (!req.context) throw new Error('request is not contextualized')
if (!req.pagePath) throw new Error('pagePath is not set on request')
if (!req.language) throw new Error('language is not set on request')
- // It's important to use `req.pagePath` instead of `req.path` because
- // the request could be the client-side routing from Next where the URL
- // might be something like `/_next/data/foo/bar.json` which is translated,
- // in another middleware, to what it would equate to if it wasn't
- // client-side routing.
- // Before executing getProductGroups, which might need to do some
- // Liquid parsing & executing, we want to make sure the request
- // does have a valid version.
- // The `currentVersion` is taken from the `req.path` but
- // `currentVersionObj` is looking up `currentVersion` with all
- // known versions. Because if it's not valid, any possible
- // use of `{% ifversion ... %}` in Liquid, will throw an error.
if (isHomepage(req.pagePath) && req.context.currentVersionObj) {
const { pages } = await warmServer([])
req.context.productGroups = await getProductGroups(pages, req.language, req.context)
diff --git a/src/frame/middleware/context/render-product-name.ts b/src/frame/middleware/context/render-product-name.ts
index 151afab5cc68..2ca7b2f85c50 100644
--- a/src/frame/middleware/context/render-product-name.ts
+++ b/src/frame/middleware/context/render-product-name.ts
@@ -12,13 +12,12 @@ export default async function renderProductName(
const { productMap, currentProduct } = req.context
if (!productMap) throw new Error('request is not contextualized')
- // `currentProduct` might be an empty string, which is a valid value.
+ // Empty currentProduct is valid.
if (currentProduct === undefined) throw new Error('currentProduct is not contextualized')
const productObject = productMap[currentProduct]
if (!productObject) {
- // If the "currentProduct" isn't recognized, there's no point trying
- // to render its name. Skip this middleware.
+ // Skip unrecognized currentProduct values because renderContent needs a product object.
return next()
}
req.context.currentProductName = await renderContent(productObject.name, req.context, {
diff --git a/src/frame/middleware/cookie-parser.ts b/src/frame/middleware/cookie-parser.ts
index ffe82e348ba0..f9bc1e2e43f2 100644
--- a/src/frame/middleware/cookie-parser.ts
+++ b/src/frame/middleware/cookie-parser.ts
@@ -5,8 +5,7 @@ import { cookieSettings } from '@/frame/lib/cookie-settings'
export default cookieParser(
process.env.COOKIE_SECRET,
- // `cookie-settings.ts` declares these as `CookieSerializeOptions` because
- // that is the right type for the places that set cookies. cookie-parser
- // wants `CookieParseOptions`, so bridge the two here.
+ // cookie-settings.ts exports CookieSerializeOptions for cookie writers.
+ // cookie-parser expects CookieParseOptions, so bridge the two here.
cookieSettings as CookieParseOptions,
)
diff --git a/src/frame/middleware/fast-head.ts b/src/frame/middleware/fast-head.ts
index 2930aeda248f..cd6475d0df32 100644
--- a/src/frame/middleware/fast-head.ts
+++ b/src/frame/middleware/fast-head.ts
@@ -8,8 +8,7 @@ export default function fastHead(req: ExtendedRequest, res: Response, next: Next
const { context } = req
const { page } = context
if (page) {
- // Since the *presence* is not affected by the request, we can cache
- // this and allow the CDN to hold on to it.
+ // Cache by URL because request headers do not change this empty HEAD response.
defaultCacheControl(res)
res.status(200).send('')
diff --git a/src/frame/middleware/fastly-cache-test.ts b/src/frame/middleware/fastly-cache-test.ts
index 4970fc9fa9be..b1908a3dbf82 100644
--- a/src/frame/middleware/fastly-cache-test.ts
+++ b/src/frame/middleware/fastly-cache-test.ts
@@ -1,19 +1,13 @@
-//
-// This middleware function is intended to be used for testing caching behavior with Fastly.
-// It will intercept ALL URLs that are routed to it and respond with a simple HTML body
-// containing a timestamp.
-// The logic will detect certain values in the path and set the HTTP status and/or the
-// Surrogate-Control header value.
-//
-// NOTE: This middleware is intended to be removed once testing is complete!
-//
+// Tests Fastly caching by returning timestamped HTML for any routed URL.
+// Path tokens set the HTTP status and cache directives.
+// X-CacheTest-CCMode chooses Surrogate-Control, Cache-Control, or both.
import express from 'express'
import crypto from 'crypto'
const router = express.Router()
router.get('/*path', function (req, res) {
- // If X-CacheTest-Error is set, simulate the site being down (regardless of URL)
+ // X-CacheTest-Error simulates a site outage for any URL.
if (req.get('X-CacheTest-Error')) {
res.status(parseInt(req.get('X-CacheTest-Error') as string)).end()
return
diff --git a/src/frame/middleware/favicons.ts b/src/frame/middleware/favicons.ts
index 44993db15454..de496bdb6245 100644
--- a/src/frame/middleware/favicons.ts
+++ b/src/frame/middleware/favicons.ts
@@ -1,8 +1,5 @@
-// We actually don't rely and use /favicon.ico but it's nevertheless a
-// very common request. Same with /apple-touch-icon.png.
-// Because we store our images, including those not for the Markdown text,
-// in the `assets/images/site` directory, we will use a custom
-// solution to serve this directly.
+// Browsers request /favicon.ico and Apple touch icons even though pages do not link them.
+// Serve these root icon URLs directly from assets/images/site.
import fs from 'fs'
import type { Response, NextFunction } from 'express'
@@ -36,10 +33,7 @@ const MAP: {
},
}
-// It's the same image but it's fine. By default, when Safari tries to
-// to figure out which apple touch icons are available it will
-// try to load this by default. For example, if you in desktop Safari
-// click share icon, it will load this to serve as a preview icon.
+// Safari probes precomposed Apple touch icon names for desktop share previews.
MAP['/apple-touch-icon-precomposed.png'] = MAP['/apple-touch-icon.png']
MAP['/apple-touch-icon-120x120-precomposed.png'] = MAP['/apple-touch-icon-120x120.png']
MAP['/apple-touch-icon-152x152-precomposed.png'] = MAP['/apple-touch-icon-152x152.png']
@@ -51,9 +45,7 @@ function getBuffer(filePath: string) {
}
return () => {
if (!buffer) {
- // Yes, sync and a bit slow, but the headers we send will
- // make sure these requests are rare because the payload
- // will be sticky in the CDN and stickly in the browser too.
+ // Sync reads are rare because assetCacheControl keeps icons in the CDN and browser cache.
buffer = fs.readFileSync(filePath)
}
return buffer
@@ -63,11 +55,10 @@ function getBuffer(filePath: string) {
export default function favicons(req: ExtendedRequest, res: Response, next: NextFunction) {
if (!MAP[req.path]) return next()
- // This makes sure the CDN caching survives each production deployment.
+ // The manual surrogate key keeps CDN caching through production deploys.
setFastlySurrogateKey(res, SURROGATE_ENUMS.MANUAL)
- // Manually settings a Cache-Control because no other middleware
- // will get a chance to do this later since we terminate here.
+ // Set asset caching here because this middleware sends the response.
assetCacheControl(res)
const { contentType, buffer } = MAP[req.path]
diff --git a/src/frame/middleware/find-page.ts b/src/frame/middleware/find-page.ts
index 7f606fc4abb4..12ea98233c80 100644
--- a/src/frame/middleware/find-page.ts
+++ b/src/frame/middleware/find-page.ts
@@ -15,18 +15,19 @@ interface FindPageOptions {
const englishPrefixRegex = /^\/en(\/|$)/
const CONTENT_ROOT = path.join(ROOT, 'content')
+// Development rereads of index pages keep startup versions and permalinks.
+// Tree construction mutates category pages from child versions, but rereads use only file data.
export default async function findPage(
req: ExtendedRequest,
res: Response,
next: NextFunction,
- // Express won't execute these but it makes it easier to unit test
- // the middleware.
+ // Express ignores these options, but tests can pass them directly.
{
isDev = process.env.NODE_ENV === 'development',
contentRoot = CONTENT_ROOT,
}: FindPageOptions = {},
): Promise {
- // Filter out things like `/will/redirect` or `/_next/data/...`
+ // Only language-prefixed content paths can map to pages; /will/redirect continues.
if (!req.pagePath || !languagePrefixPathRegex.test(req.pagePath)) {
return next()
}
@@ -37,11 +38,6 @@ export default async function findPage(
let page = req.context.pages[req.pagePath] as Page | undefined
if (page && isDev && englishPrefixRegex.test(req.pagePath)) {
- // The .applicableVersions and .permalinks properties are computed
- // when the page is read in from disk. But when the initial tree
- // was created at startup, the pages in the tree were mutated
- // based on their context. For example, a category page's versions
- // is based on looping through all its children's versions.
const reuseOldVersions = page.relativePath.endsWith('index.md')
const oldApplicableVersions = page.applicableVersions
const oldPermalinks = page.permalinks
@@ -59,9 +55,7 @@ export default async function findPage(
page.permalinks = oldPermalinks
}
- // This can happen if the page we just re-read has changed which
- // versions it's available in (the `versions` frontmatter) meaning
- // it might no longer be available on the current URL.
+ // A reread page can drop the requested version from applicableVersions.
if (
req.context?.currentVersion &&
!page.applicableVersions.includes(req.context.currentVersion)
@@ -80,9 +74,7 @@ export default async function findPage(
req.context.page = page
;(req.context.page as Page & { version: string }).version = req.context.currentVersion || ''
- // We can't depend on `page.hidden` because the dedicated search
- // results page is a hidden page but it needs to offer all possible
- // languages.
+ // page.hidden also hides search, which needs every language; restrict only early-access pages.
if (page.relativePath.startsWith('early-access') && req.context?.languages?.en) {
req.context.languages = {
en: req.context.languages.en,
@@ -93,6 +85,7 @@ export default async function findPage(
return next()
}
+// rereadByPath handles only English content because translations load at build time.
async function rereadByPath(
uri: string,
contentRoot: string,
@@ -103,18 +96,12 @@ async function rereadByPath(
const languageCode = match[1]
const withoutLanguage = uri.replace(languagePrefixPathRegex, '/')
const withoutVersion = withoutLanguage.replace(`/${currentVersion}`, '')
- // Note: We don't support loading translations at runtime. All translations
- // are loaded at build time. This function only handles English content reloading
- // during development.
const possible = path.join(contentRoot, withoutVersion)
const filePath = existsSync(possible) ? path.join(possible, 'index.md') : `${possible}.md`
const relativePath = path.relative(contentRoot, filePath)
const basePath = contentRoot
- // Remember, the Page.init() can return a Promise that resolves to falsy
- // if it can't read the file in from disk. E.g. a request for /en/non/existent.
- // In other words, it's fine if it can't be read from disk. It'll get
- // handled and turned into a nice 404 message.
+ // When a reread fails, the caller keeps the already-found page.
const page = await Page.init({
basePath,
relativePath,
diff --git a/src/frame/middleware/handle-next-data-path.ts b/src/frame/middleware/handle-next-data-path.ts
index 882720748ce0..78eb3e6748b9 100644
--- a/src/frame/middleware/handle-next-data-path.ts
+++ b/src/frame/middleware/handle-next-data-path.ts
@@ -5,16 +5,15 @@ import type { ExtendedRequest } from '@/types'
const STATSD_KEY = 'middleware.handle_next_data_path'
+// Client route transitions request _next/data JSON paths; map them back to page paths.
+// Example: /_next/data/development/en/actions/foo.json becomes
+// /en/actions/foo.
export default function handleNextDataPath(
req: ExtendedRequest,
res: Response,
next: NextFunction,
) {
if (req.path.startsWith('/_next/data/') && req.path.endsWith('.json')) {
- // translate a nextjs data request to a page path that the server can use on context
- // this is triggered via client-side route transitions
- // example path:
- // /_next/data/development/en/free-pro-team%40latest/github/setting-up-and-managing-your-github-user-account.json
let decodedPath = ''
try {
decodedPath = decodeURIComponent(req.path)
@@ -26,7 +25,7 @@ export default function handleNextDataPath(
}
const parts = decodedPath.split('/').slice(4)
- // free-pro-team@latest should not be included in the page path
+ // Drop free-pro-team@latest because page paths omit that default version.
if (parts[1] === 'free-pro-team@latest') {
parts.splice(1, 1)
}
diff --git a/src/frame/middleware/healthcheck.ts b/src/frame/middleware/healthcheck.ts
index 68e3089b17d5..514e1688ee53 100644
--- a/src/frame/middleware/healthcheck.ts
+++ b/src/frame/middleware/healthcheck.ts
@@ -4,11 +4,8 @@ import statsd from '@/observability/lib/statsd'
const router = express.Router()
-// Returns the healthiness of the service.
-// Moda may use this to decide whether this instance stays in the pool.
-// Today it checks nothing and always returns 200. If we ever needed to drain
-// an instance, for example on a failing dependency, this is where a 500
-// would go.
+// Moda may use this endpoint to decide whether an instance stays in the pool.
+// It always returns 200 and sends memory gauges to StatsD, without testing service health.
router.get('/', function healthcheck(req, res) {
noCacheControl(res)
diff --git a/src/frame/middleware/helmet.ts b/src/frame/middleware/helmet.ts
index ddbd4b90e8a1..7814bcde5975 100644
--- a/src/frame/middleware/helmet.ts
+++ b/src/frame/middleware/helmet.ts
@@ -9,11 +9,8 @@ import { colorModeScript } from '@/color-schemes/lib/color-mode-script'
const isDev = process.env.NODE_ENV === 'development'
-// The pre-paint theme script in `_document.tsx` is inlined, so it needs an
-// explicit CSP `script-src` allowance. We hash the exact script string rather
-// than using a nonce, because a nonce would have to vary per response and would
-// break the shared CDN cache. The script is identical for every request, so its
-// hash is stable and the HTML stays cacheable.
+// The pre-paint theme script from _document.tsx is inline, so CSP needs a script-src hash.
+// A nonce would vary per response and break shared CDN caching.
const colorModeScriptHash = `'sha256-${createHash('sha256').update(colorModeScript).digest('base64')}'`
const GITHUB_DOMAINS = [
"'self'",
@@ -29,22 +26,19 @@ const DEFAULT_OPTIONS = {
referrerPolicy: {
policy: 'no-referrer-when-downgrade' as const,
},
- // This module defines a Content Security Policy (CSP) to disallow
- // inline scripts and content from untrusted sources.
+ // The default CSP blocks untrusted origins and limits inline scripts to approved hashes.
contentSecurityPolicy: {
directives: {
defaultSrc: ["'none'"],
prefetchSrc: ["'self'"],
- // When doing local dev, especially in Safari, you need to add `ws:`
- // which NextJS uses for the hot module reloading.
+ // Safari local development needs ws: for Next.js hot module reloading.
connectSrc: ["'self'", 'https://collector.githubapp.com', isDev && 'ws:'].filter(
Boolean,
) as string[],
fontSrc: ["'self'", 'data:'],
imgSrc: [...GITHUB_DOMAINS, 'data:', 'placehold.it'],
objectSrc: ["'self'"],
- // For use during development only!
- // `unsafe-eval` allows us to use a performant webpack devtool setting (eval)
+ // Development webpack eval devtool needs unsafe-eval.
// https://webpack.js.org/configuration/devtool/#devtool
scriptSrc: [
...GITHUB_DOMAINS,
@@ -57,16 +51,17 @@ const DEFAULT_OPTIONS = {
frameSrc: [
...GITHUB_DOMAINS,
isDev && 'http://localhost:3000',
- // ArticleContext.tsx sets this URL too. We don't import a shared
- // constant because the env var may not be set yet at import time.
+ // src/frame/components/context/ArticleContext.tsx sets this URL too.
+ // A shared constant could capture SUPPORT_PORTAL_URL before it is set.
process.env.NODE_ENV === 'production'
? 'https://support.github.com'
- : // Assume that a developer is not testing the VA iframe locally if this env var is not set
+ : // Missing SUPPORT_PORTAL_URL means local development is not testing the VA iframe.
process.env.SUPPORT_PORTAL_URL || '',
].filter(Boolean) as string[],
frameAncestors: isDev ? ['*'] : [...GITHUB_DOMAINS],
styleSrc: [...GITHUB_DOMAINS, "'self'", "'unsafe-inline'", 'data:'],
- childSrc: ["'self'"], // exception for search in deprecated GHE versions
+ // Deprecated GitHub Enterprise search still needs child-src.
+ childSrc: ["'self'"],
manifestSrc: ["'self'"],
upgradeInsecureRequests: isDev ? null : [],
},
@@ -100,23 +95,21 @@ const staticDeprecatedHelmet = helmet(STATIC_DEPRECATED_OPTIONS)
const developerDeprecatedHelmet = helmet(DEVELOPER_DEPRECATED_OPTIONS)
export default function helmetMiddleware(req: Request, res: Response, next: NextFunction) {
- // Enable CORS
if (['GET', 'OPTIONS'].includes(req.method)) {
res.set('access-control-allow-origin', '*')
}
- // Determine version for exceptions
const { requestedVersion } = isArchivedVersion(req)
- // Check if this is a legacy developer.github.com path
const isDeveloper = req.path
.replace(languagePrefixPathRegex, '/')
.startsWith(`/enterprise/${requestedVersion}/developer`)
if (versionSatisfiesRange(requestedVersion, '<=2.18') && isDeveloper) {
+ // Deprecated developer.github.com paths need Google font and inline script exceptions.
return developerDeprecatedHelmet(req, res, next)
}
- // Exception for deprecated Enterprise docs (Node.js era)
+ // Node.js-era deprecated Enterprise docs need relaxed CSP directives.
if (
versionSatisfiesRange(requestedVersion, '<=2.19') &&
versionSatisfiesRange(requestedVersion, '>2.12')
@@ -124,7 +117,7 @@ export default function helmetMiddleware(req: Request, res: Response, next: Next
return nodeDeprecatedHelmet(req, res, next)
}
- // Exception for search in deprecated Enterprise docs <=2.12 (static site era)
+ // Static-site-era Enterprise search needs inline scripts.
if (versionSatisfiesRange(requestedVersion, '<=2.12')) {
return staticDeprecatedHelmet(req, res, next)
}
diff --git a/src/frame/middleware/index.ts b/src/frame/middleware/index.ts
index d4070063dd82..41aa501ce6a8 100644
--- a/src/frame/middleware/index.ts
+++ b/src/frame/middleware/index.ts
@@ -69,7 +69,7 @@ import urlDecode from './url-decode'
const ENABLE_FASTLY_TESTING = JSON.parse(process.env.ENABLE_FASTLY_TESTING || 'false')
-// Catch unhandled promise rejections and passing them to Express's error handler
+// asyncMiddleware passes unhandled promise rejections to Express's error handler.
// https://medium.com/@Abazhenov/using-async-await-in-express-with-node-8-b8af872c0016
const asyncMiddleware =
(
@@ -83,63 +83,38 @@ const asyncMiddleware =
}
}
+// trust proxy makes req.ip read the left-most X-Forwarded-For value for rate limits and logs.
+// https://expressjs.com/en/guide/behind-proxies.html
export default function index(app: Express) {
app.use(abort)
- // Don't use the proxy's IP, use the requester's for rate limiting or
- // logging.
- // See https://expressjs.com/en/guide/behind-proxies.html
- // Essentially, setting this means it believe that the IP is the
- // first of the `X-Forwarded-For` header values.
- // If it was 0 (or false), the value would be that
- // of `req.socket.remoteAddress`.
- // Now, the `req.ip` becomes the first entry from x-forwarded-for
- // and falls back on `req.socket.remoteAddress` in all other cases.
- // Their documentation says:
- //
- // If true, the client's IP address is understood as the
- // left-most entry in the X-Forwarded-For header.
- //
app.set('trust proxy', true)
- // *** Logging ***
- app.use(initLoggerContext) // Context for both inline logs (e.g. logger.info) and automatic logs
- app.use(getAutomaticRequestLogger()) // Automatic logging for all requests e.g. "GET /path 200"
- app.use(expressMetrics) // StatsD metrics for response time and status codes
+ app.use(initLoggerContext)
+ app.use(getAutomaticRequestLogger())
+ app.use(expressMetrics)
- // Put this early to make it as fast as possible because it's used
- // to check the health of each cluster.
+ // Keep healthcheck early so cluster probes skip slower middleware.
app.use('/healthcheck', healthcheck)
- // Must appear before static assets and all other requests
- // otherwise we won't be able to benefit from that functionality
- // for static assets as well.
+ // Default surrogate keys must run before static assets, so static responses can inherit them.
app.use(setDefaultFastlySurrogateKey)
- // Attaches res.safeRedirect() to every response. Must appear before
- // any middleware that redirects.
+ // safeRedirect must run before middleware that redirects.
app.use(safeRedirect)
- // archivedEnterpriseVersionsAssets must come before static/assets
+ // archivedEnterpriseVersionsAssets must run before static asset middleware.
app.use(asyncMiddleware(archivedEnterpriseVersionsAssets))
app.use(favicons)
- // Any static URL that contains some sort of checksum that makes it
- // unique gets the "manual" surrogate key. If it's checksummed,
- // it's bound to change when it needs to change. Otherwise,
- // we want to make sure it doesn't need to be purged just because
- // there's a production deploy.
- // Note, for `/assets/cb-*...` requests,
- // this needs to come before `assetPreprocessing` because
- // the `assetPreprocessing` middleware will rewrite `req.url` if
- // it applies.
+ // Checksummed assets keep manual keys; assetPreprocessing later rewrites /assets/cb-* URLs.
app.use(setStaticAssetCaching)
- // Must come before any other middleware for assets
+ // archivedAssetRedirects must run before other asset middleware.
app.use(archivedAssetRedirects)
- // This must come before the express.static('assets') middleware.
+ // assetPreprocessing must run before express.static assets.
app.use(assetPreprocessing)
app.use(
@@ -147,11 +122,10 @@ export default function index(app: Express) {
express.static('assets', {
index: false,
etag: false,
- // Can be aggressive because images inside the content get unique
- // URLs with a cache busting prefix.
+ // Content image URLs have cache-busting prefixes, so assets can cache aggressively.
maxAge: '7 days',
immutable: process.env.NODE_ENV !== 'development',
- // The next middleware will try its luck and send the 404 if must.
+ // Let later middleware send the asset 404.
fallthrough: true,
}),
)
@@ -161,15 +135,13 @@ export default function index(app: Express) {
express.static('src/graphql/data', {
index: false,
etag: false,
- maxAge: '7 days', // A bit longer since releases are more sparse
- // See note about the use of 'fallthrough'
+ maxAge: '7 days', // Sparse releases tolerate longer caching.
+ // Missing release assets 404 here.
fallthrough: false,
}),
)
- // In development, let NextJS on-the-fly serve the static assets.
- // But in production, don't let NextJS handle any static assets
- // because they are costly to generate (the 404 HTML page).
+ // In production, skip Next static handling because generated 404 HTML is expensive.
if (process.env.NODE_ENV !== 'development') {
const assetDir = path.join('.next', 'static')
if (!fs.existsSync(assetDir))
@@ -182,60 +154,52 @@ export default function index(app: Express) {
etag: false,
maxAge: '365 days',
immutable: true,
- // See note about the use of 'fallthrough'
+ // Missing Next assets 404 here.
fallthrough: false,
}),
)
}
- // *** Early exits ***
app.use(shielding)
app.use(handleNextDataPath)
- // *** Security ***
app.use(helmet)
app.use(cookieParser)
app.use(express.json())
if (process.env.NODE_ENV === 'development') {
- app.use(mockVaPortal) // FOR TESTING.
+ app.use(mockVaPortal)
}
- // *** Headers ***
- app.set('etag', false) // We will manage our own ETags if desired
+ app.set('etag', false) // Disable Express ETags so middleware can set them explicitly when needed.
- // *** Config and context for redirects ***
- app.use(urlDecode) // Must come before detectLanguage to decode @ symbols in version segments
- app.use(detectLanguage) // Must come before context, breadcrumbs, find-page, handle-errors, homepages
- app.use(detectVersion) // Must come before handle-redirects for version cookie support
- app.use(asyncMiddleware(reloadTree)) // Must come before context
- app.use(asyncMiddleware(context)) // Must come before early-access-*, handle-redirects
- app.use(shortVersions) // Support version shorthands
- app.use(asyncMiddleware(renderProductName)) // Must come after shortVersions
+ app.use(urlDecode) // Must run before detectLanguage to decode @ symbols in version segments.
+ // Must run before context, breadcrumbs, findPage, handleErrors, and homepages.
+ app.use(detectLanguage)
+ app.use(detectVersion) // Must run before handleRedirects for version cookie support.
+ app.use(asyncMiddleware(reloadTree)) // Must run before context.
+ app.use(asyncMiddleware(context)) // Must run before earlyAccessLinks and handleRedirects.
+ app.use(shortVersions)
+ app.use(asyncMiddleware(renderProductName)) // Must run after shortVersions.
- // Must come before handleRedirects.
- // This middleware might either redirect or serve something.
+ // archivedEnterpriseVersions must run before handleRedirects because it can redirect or serve.
app.use(asyncMiddleware(archivedEnterpriseVersions))
- // *** Redirects, 3xx responses ***
- // I ordered these by use frequency
app.use(trailingSlashes)
- app.use(languageCodeRedirects) // Must come before contextualizers
- app.use(handleRedirects) // Must come before contextualizers
+ app.use(languageCodeRedirects) // Must run before contextualizers.
+ app.use(handleRedirects) // Must run before contextualizers.
- // *** Config and context for rendering ***
- app.use(asyncMiddleware(findPage)) // Must come before archived-enterprise-versions, breadcrumbs, featured-links, products, render-page
+ // Must run before breadcrumbs, featuredLinks, productGroups, and renderPage.
+ app.use(asyncMiddleware(findPage))
app.use(blockRobots)
- // *** Rendering, 2xx responses ***
app.use('/api', api)
app.use('/llms.txt', llmsTxt)
app.get('/_build', buildInfo)
app.get('/_req-headers', reqHeaders)
app.use(asyncMiddleware(manifestJson))
- // Things like `/api` sets their own Fastly surrogate keys.
- // Now that the `req.language` is known, set it for the remaining endpoints
+ // After req.language exists, remaining endpoints get language keys; /api keeps its own.
app.use(setLanguageFastlySurrogateKey)
app.use(robots)
@@ -243,16 +207,14 @@ export default function index(app: Express) {
app.use('/categories.json', asyncMiddleware(categoriesForSupport))
app.get('/_500', asyncMiddleware(triggerError))
- // Specifically deal with HEAD requests before doing the slower
- // full page rendering.
+ // HEAD requests skip slower full page rendering.
app.head('/*path', fastHead)
- // *** Preparation for render-page: contextualizers ***
app.use(asyncMiddleware(dataTables))
app.use(asyncMiddleware(secretScanning))
app.use(asyncMiddleware(ghesReleaseNotes))
app.use(layout)
- app.use(features) // needs to come before product tree
+ app.use(features) // Must run before currentProductTree.
app.use(asyncMiddleware(currentProductTree))
app.use(asyncMiddleware(genericToc))
app.use(breadcrumbs)
@@ -264,18 +226,15 @@ export default function index(app: Express) {
app.use(asyncMiddleware(journeyTrack))
if (ENABLE_FASTLY_TESTING) {
- // The fastlyCacheTest middleware is intended to be used with Fastly to test caching behavior.
- // This middleware will intercept ALL requests routed to it, so be careful if you need to
- // make any changes to the following line:
+ // fastlyCacheTest intercepts all routed requests, so keep the route narrow.
app.use('/fastly-cache-test', fastlyCacheTest)
}
- // handle serving NextJS bundled code (/_next/*)
app.use(next)
- // *** Rendering, must go almost last ***
+ // renderPage must run after specialized routes.
app.get('/*path', asyncMiddleware(renderPage))
- // *** Error handling, must go last ***
+ // handleErrors must run last to catch middleware errors.
app.use(handleErrors)
}
diff --git a/src/frame/middleware/manifest-json.ts b/src/frame/middleware/manifest-json.ts
index 851ca6ce5f11..1e40440f39b1 100644
--- a/src/frame/middleware/manifest-json.ts
+++ b/src/frame/middleware/manifest-json.ts
@@ -30,21 +30,16 @@ export default async function manifestJson(req: Request, res: Response, next: Ne
}
if (req.url !== '/manifest.json') {
- // E.g. `/manifest.json/anything` or `/manifest.json?foo=bar`
+ // Examples: /manifest.json/anything and /manifest.json?foo=bar.
defaultCacheControl(res)
return res.safeRedirect(302, '/manifest.json')
}
const icons: Icon[] = []
- // This is modelled after https://github.com/manifest.json
+ // The manifest mirrors https://github.com/manifest.json.
const manifest = {
- // In the future we might want to have a different manifest for each
- // language. Particularly, the `name` property.
- // But as of May 2023, this is overkill because all translations's
- // home page refer to the name of the site as "GitHub Docs".
- // For example, on https://docs.github.com/ja the ``
- // is "GitHub Docs".
+ // Localized home pages title the site GitHub Docs, so one manifest covers every language.
name: 'GitHub Docs',
short_name: 'GitHub Docs',
start_url: '/',
diff --git a/src/frame/middleware/mock-va-portal.ts b/src/frame/middleware/mock-va-portal.ts
index cafc8781dc4d..be2647716ba9 100644
--- a/src/frame/middleware/mock-va-portal.ts
+++ b/src/frame/middleware/mock-va-portal.ts
@@ -1,15 +1,4 @@
-// Mocks the VA portal so you can test the VA integration without access to a
-// staging VA portal. You can't point at the production one either, because it
-// is hardened to https://docs.github.com and will reject your localhost:4000.
-//
-// To test locally:
-//
-// 1. Add `SUPPORT_PORTAL_URL=http://localhost:4000` to your `.env` file
-// 2. `npm run dev`
-// 3. Navigate to a page listed in the `PagePathToVaFlowMapping` object in
-// the `ArticleContext`.
-//
-// This mocking is not secure. It is only for local development.
+// Local-only Virtual Assistant portal mock; the production portal rejects localhost:4000.
import type { Response, NextFunction } from 'express'
diff --git a/src/frame/middleware/next.ts b/src/frame/middleware/next.ts
index bc50942ffeae..a467ddffc588 100644
--- a/src/frame/middleware/next.ts
+++ b/src/frame/middleware/next.ts
@@ -12,8 +12,7 @@ export const nextHandleRequest = nextApp.getRequestHandler()
await nextApp.prepare()
function renderPageWithNext(req: ExtendedRequest, res: Response, nextFn: NextFunction) {
- // This catches URLs like `/_next/webpack-hmr` and
- // `/_next/static/webpack/64e44ef62e261d3a.webpack.hot-update.json`.
+ // _next asset and HMR requests, like /_next/webpack-hmr, bypass docs routing.
if (req.path.startsWith('/_next') && !req.path.startsWith('/_next/data')) {
return nextHandleRequest(req, res)
}
diff --git a/src/frame/middleware/reload-tree.ts b/src/frame/middleware/reload-tree.ts
index 3007311e64c4..4432194a54dc 100644
--- a/src/frame/middleware/reload-tree.ts
+++ b/src/frame/middleware/reload-tree.ts
@@ -1,13 +1,7 @@
-// This exists for local reviewing only.
-//
-// We load the entire tree on startup and use it for sidebars, breadcrumbs,
-// landing pages, and ToC pages. In development, an individual English page is
-// reread from disk on each request in case it changed, but doing that for all
-// 1k+ pages is not feasible.
-//
-// So this middleware calls `createTree()` with the previous tree, letting
-// `createTree` reuse the pages that haven't changed on disk. That way things
-// like sidebars refresh without restarting the server.
+// The app loads the full tree at startup for sidebars, breadcrumbs, landing pages, and ToC pages.
+// This development-only middleware rereads individual English pages per request.
+// Rereading all 1k+ pages per request would be too slow.
+// createTree receives the previous tree, so navigation refreshes without restarting the server.
import path from 'path'
@@ -27,15 +21,14 @@ const isDev = process.env.NODE_ENV === 'development'
export default async function reloadTree(req: ExtendedRequest, res: Response, next: NextFunction) {
if (!isDev) return next()
- // Filter out things like `/will/redirect` or `/_next/data/...`
+ // Only language-prefixed content paths can refresh the tree; /will/redirect continues.
if (!req.pagePath || !languagePrefixRegex.test(req.pagePath)) return next()
- // We only bother if the loaded URL is something `/en/...`
+ // Only English content can refresh the development tree.
if (!englishPrefixRegex.test(req.pagePath)) return next()
const warmed = await warmServer([])
- // For all the real English content, this usually takes about 30-60ms on
- // an Intel MacBook Pro.
+ // createTree below usually takes 30-60ms for real English content on an Intel MacBook Pro.
const before = getMtimes(warmed.unversionedTree.en)
warmed.unversionedTree.en = (await createTree(
path.join(languages.en.dir, 'content'),
@@ -43,11 +36,7 @@ export default async function reloadTree(req: ExtendedRequest, res: Response, ne
warmed.unversionedTree.en,
)) as UnversionedTree
const after = getMtimes(warmed.unversionedTree.en)
- // The next couple of operations are much slower (in total) than
- // refreshing the tree. So we want to know if the tree changed before
- // bothering.
- // If refreshing of the `.en` part of the `unversionedTree` takes 40ms
- // then the following operations takes about 140ms.
+ // Dependent maps take about 140ms after a 40ms tree refresh, so skip them when mtimes match.
if (before !== after) {
warmed.siteTree = (await loadSiteTree(warmed.unversionedTree)) as SiteTree
warmed.pageList = await loadPages(warmed.unversionedTree)
@@ -58,10 +47,7 @@ export default async function reloadTree(req: ExtendedRequest, res: Response, ne
return next()
}
-// Given a tree, return a number that represents the mtimes for all pages
-// in the tree.
-// You can use this to compute it before and after the tree is (maybe)
-// mutated and if the numbers *change* you can know the tree changed.
+// Summing mtimes lets reloadTree detect page changes before rebuilding slower maps.
function getMtimes(tree: UnversionedTree) {
let mtimes = tree.page.mtime
for (const child of tree.childPages || []) {
diff --git a/src/frame/middleware/render-page.ts b/src/frame/middleware/render-page.ts
index 0aed59fe722e..1d3e0b4b7d2a 100644
--- a/src/frame/middleware/render-page.ts
+++ b/src/frame/middleware/render-page.ts
@@ -27,8 +27,7 @@ async function buildRenderedPage(req: ExtendedRequest): Promise<string> {
if (!page) throw new Error('page not set in context')
const path = req.pagePath || req.path
- // Set up collection array for the collect-mini-toc rehype plugin only when
- // the page actually needs a mini-TOC, avoiding unnecessary work.
+ // Collect mini-TOC headings only for pages that show one, so other renders avoid plugin work.
if (page.showMiniToc) {
const collectMiniToc: CollectedHeading[] = []
context.collectMiniToc = collectMiniToc
@@ -41,16 +40,10 @@ async function buildRenderedPage(req: ExtendedRequest): Promise<string> {
return (await pageRenderTimed(context)) as string
}
-// Spike for #6619: produce the article body as a serializable hast (HTML AST)
-// tree alongside the legacy HTML string.
-//
-// Must run AFTER buildRenderedPage, which calls page.render and populates the
-// context fields the pipeline reads (englishHeadings, alertTitles). We render
-// the same raw `page.markdown`, but with a context clone that omits
-// `collectMiniToc` so the mini-TOC isn't collected a second time.
-//
-// Wrapped so a hast failure can never break the page. The React layer falls
-// back to the string path when this is undefined.
+// buildRenderedPageHast returns a serializable HTML AST alongside renderedPage.
+// It runs after buildRenderedPage because page.render populates englishHeadings and alertTitles.
+// It disables collectMiniToc so mini-TOC collection does not repeat.
+// Failures return undefined, and the React layer falls back to renderedPage.
async function buildRenderedPageHast(req: ExtendedRequest) {
const { context } = req
if (!context) throw new Error('request not contextualized')
@@ -76,12 +69,11 @@ function buildMiniTocItems(req: ExtendedRequest) {
if (!context) throw new Error('request not contextualized')
const { page } = context
- // get mini TOC items on articles
if (!page || !page.showMiniToc) {
return
}
- // Use headings collected during rendering via the collect-mini-toc rehype plugin.
+ // Collected headings avoid rendering article content a second time.
const collected = context.collectMiniToc as CollectedHeading[] | undefined
if (collected) {
return buildMiniTocFromCollected(collected, 2)
@@ -91,15 +83,13 @@ function buildMiniTocItems(req: ExtendedRequest) {
export default async function renderPage(req: ExtendedRequest, res: Response) {
const { context } = req
- // `Error.getInitialProps`, which NextJS runs on errors, reads this off the
- // request so it can send the error to Failbot.
+ // Next.js Error.getInitialProps reads req.FailBot so it can report errors to Failbot.
req.FailBot = FailBot as Failbot
if (!context) throw new Error('request not contextualized')
const { page } = context
const path = req.pagePath || req.path
- // render a 404 page
if (!page) {
if (process.env.NODE_ENV !== 'test' && context.redirectNotFound) {
logger.error('Tried to redirect to a page that was not found', {
@@ -107,27 +97,23 @@ export default async function renderPage(req: ExtendedRequest, res: Response) {
})
}
- // send minimal 404 at this point since we ran into hydration issues trying to pass
- // these along to AppRouter 404 handling
+ // Passing this context to App Router 404 handling causes hydration failures.
defaultCacheControl(res)
return res.status(404).type('html').send(minimumNotFoundHtml)
}
- // Just finish fast without all the details like Content-Length
+ // HEAD skips page rendering but still lets Express send Content-Length: 0.
if (req.method === 'HEAD') {
return res.status(200).send('')
}
- // Updating the Last-Modified header for substantive changes on a page for engineering
- // Docs Engineering Issue #945
+ // effectiveDate marks substantive page changes for clients that watch Last-Modified.
if (page.effectiveDate) {
- // The frontmatter schema only checks that this is a string. An unparseable
- // date gets caught later, in ArticleContext, and ends up as a 500.
+ // ArticleContext turns unparseable effectiveDate strings into a 500.
res.setHeader('Last-Modified', new Date(page.effectiveDate).toUTCString())
}
- // Content negotiation: serve markdown when the client prefers it over HTML.
- // Agents like Claude Code send Accept headers that omit text/html.
+ // Serve markdown when the client prefers it over HTML; agents can omit text/html.
if (req.accepts(['text/html', 'text/markdown']) === 'text/markdown') {
context.markdownRequested = true
}
@@ -137,10 +123,7 @@ export default async function renderPage(req: ExtendedRequest, res: Response) {
if (context.markdownRequested) {
const transformer = transformerRegistry.findTransformer(page)
if (!transformer) throw new Error(`No transformer found for page: ${req.pagePath}`)
- // Pass context without markdownRequested, because transformers set it
- // themselves when rendering templates. Having it set during prepareTemplateData()
- // causes renderTitle/renderProp to output markdown instead of HTML,
- // which breaks the cheerio-based unwrap logic.
+ // Clear markdownRequested so renderTitle and renderProp output HTML for stripOuterTag.
const transformerContext = { ...context, markdownRequested: false }
req.context.renderedPage = normalizeRenderedMarkdown(
await transformer.transform(page, path, transformerContext),
@@ -153,7 +136,6 @@ export default async function renderPage(req: ExtendedRequest, res: Response) {
page.fullTitle = page.title
- // add localized ` - GitHub Docs` suffix to <title> tag (except for the homepage)
if (!patterns.homepagePath.test(path)) {
if (
req.context.currentVersion === 'free-pro-team@latest' ||
@@ -163,9 +145,7 @@ export default async function renderPage(req: ExtendedRequest, res: Response) {
} else {
const { versionTitle } = allVersions[req.context.currentVersion!]
page.fullTitle += ' - '
- // Some plans don't have the word "GitHub" in them.
- // E.g. "Enterprise Server 3.5"
- // In those cases manually prefix the word "GitHub" before it.
+ // Prefix version titles that omit GitHub.
if (!versionTitle.includes('GitHub')) {
page.fullTitle += 'GitHub '
}
@@ -178,15 +158,15 @@ export default async function renderPage(req: ExtendedRequest, res: Response) {
if (isRequestingJsonForDebugging) {
const json = req.query.json
if (Array.isArray(json)) {
- // e.g. ?json=page.permalinks&json=currentPath
+ // Example: ?json=page.permalinks&json=currentPath.
throw new Error("'json' query string can only be 1")
}
if (json) {
- // deep reference: ?json=page.permalinks
+ // Example deep reference: ?json=page.permalinks.
return res.json(get(context, req.query.json as string))
} else {
- // dump all the keys: ?json
+ // Example full key dump: ?json.
return res.json({
message:
'The full context object is too big to display! Try one of the individual keys below, e.g. ?json=page. You can also access nested props like ?json=site.data.reusables',
diff --git a/src/frame/middleware/resolve-carousels.ts b/src/frame/middleware/resolve-carousels.ts
index 2aa68876923b..a69c60253eff 100644
--- a/src/frame/middleware/resolve-carousels.ts
+++ b/src/frame/middleware/resolve-carousels.ts
@@ -6,7 +6,7 @@ import Permalink from '@/frame/lib/permalink'
import { createLogger } from '@/observability/logger/index'
-// The Page class has rawCarousels and carousels properties that aren't on the Page type
+// Page adds rawCarousels and carousels at runtime, but the Page type omits them.
interface PageCarouselProps {
rawCarousels?: Record<string, string[]>
carousels?: Record<string, ResolvedArticle[]>
@@ -20,6 +20,7 @@ function buildArticlePath(currentLanguage: string, articlePath: string, basePath
return `${pathPrefix}${separator}${articlePath}`
}
+// Resolve carousel paths as content-relative, then page-relative, then retry both with .md.
function tryResolveArticlePath(
rawPath: string,
pageRelativePath: string | undefined,
@@ -32,7 +33,6 @@ function tryResolveArticlePath(
return undefined
}
- // Strategy 1: Try content-relative path (add language prefix to raw path)
const contentRelativePath = buildArticlePath(currentLanguage, rawPath)
let foundPage = findPage(contentRelativePath, pages, redirects)
@@ -40,7 +40,6 @@ function tryResolveArticlePath(
return foundPage
}
- // Strategy 2: Try page-relative path if page context is available
if (pageRelativePath) {
const pageDirPath = pageRelativePath.split('/').slice(0, -1).join('/')
const pageRelativeFullPath = buildArticlePath(currentLanguage, rawPath, pageDirPath)
@@ -51,11 +50,9 @@ function tryResolveArticlePath(
}
}
- // Strategy 3: Try with .md extension if not already present
if (!rawPath.endsWith('.md')) {
const pathWithExtension = `${rawPath}.md`
- // Try Strategy 1 with .md extension
const contentRelativePathWithExt = buildArticlePath(currentLanguage, pathWithExtension)
foundPage = findPage(contentRelativePathWithExt, pages, redirects)
@@ -63,7 +60,6 @@ function tryResolveArticlePath(
return foundPage
}
- // Try Strategy 2 with .md extension
if (pageRelativePath) {
const pageDirPath = pageRelativePath.split('/').slice(0, -1).join('/')
const pageRelativeFullPathWithExt = buildArticlePath(
@@ -82,7 +78,6 @@ function tryResolveArticlePath(
return foundPage
}
-// Returns a page's path without the language or version prefix.
function getPageHref(page: Page): string {
if (page.relativePath) {
return Permalink.relativePathToSuffix(page.relativePath)
@@ -137,7 +132,7 @@ async function resolveCarousels(
}
if (resolved.length > 0) {
- // Prevent prototype pollution by rejecting __proto__ keys
+ // Reject unsafe object keys to prevent prototype pollution.
if (
carouselKey !== '__proto__' &&
carouselKey !== 'constructor' &&
diff --git a/src/frame/middleware/robots.ts b/src/frame/middleware/robots.ts
index 11d17680d6f3..137b9ef7d8c9 100644
--- a/src/frame/middleware/robots.ts
+++ b/src/frame/middleware/robots.ts
@@ -17,7 +17,7 @@ export default function robots(req: ExtendedRequest, res: Response, next: NextFu
const host = req.get('x-host') || req.get('x-forwarded-host') || req.get('host')
- // only include robots.txt when it's our production domain and adding localhost for robots-txt.ts test
+ // Allow indexing only on docs.github.com and 127.0.0.1 for tests.
if (
host === 'docs.github.com' ||
req.hostname === 'docs.github.com' ||
diff --git a/src/frame/middleware/safe-redirect.ts b/src/frame/middleware/safe-redirect.ts
index 0c875bfe9ed7..128b0418ec47 100644
--- a/src/frame/middleware/safe-redirect.ts
+++ b/src/frame/middleware/safe-redirect.ts
@@ -2,20 +2,19 @@ import type { Response, NextFunction } from 'express'
import type { ExtendedRequest } from '@/types'
-// Normalizes a redirect URL to prevent open redirects via protocol-relative
-// URLs (e.g. "//evil.com" which browsers interpret as "https://evil.com").
+// Strip protocol-relative prefixes so browsers cannot turn redirects into external URLs.
+// Example: //evil.com becomes /evil.com.
export function safeRedirectUrl(url: string): string {
return url.replace(/^\/\/+/, '/')
}
-// Matches the overloaded signature of Express's res.redirect().
+// SafeRedirect matches the overloaded signature of Express res.redirect.
export type SafeRedirect = {
(url: string): void
(status: number, url: string): void
}
-// Attaches res.safeRedirect() to the response for all downstream middleware.
-// Same signature as res.redirect() but normalizes the URL first.
+// Downstream middleware calls res.safeRedirect with the Express redirect signature.
export default function safeRedirect(req: ExtendedRequest, res: Response, next: NextFunction) {
res.safeRedirect = function (statusOrUrl: number | string, url?: string) {
if (typeof statusOrUrl === 'number' && url !== undefined) {
diff --git a/src/frame/middleware/set-fastly-surrogate-key.ts b/src/frame/middleware/set-fastly-surrogate-key.ts
index a455d661a4f3..23394048441e 100644
--- a/src/frame/middleware/set-fastly-surrogate-key.ts
+++ b/src/frame/middleware/set-fastly-surrogate-key.ts
@@ -3,15 +3,12 @@ import type { Request, Response, NextFunction } from 'express'
import { ExtendedRequest } from '@/types'
import type { Page, Version } from '@/types'
-// Fastly provides a Soft Purge feature that allows you to mark content as outdated (stale) instead of permanently
-// purging and thereby deleting it from Fastly's caches. Objects invalidated with Soft Purge will be treated as
-// outdated (stale) while Fastly fetches a new version from origin.
-//
-// Use of a surrogate key is required for soft purging
+// Fastly soft purges mark cached objects stale while origin fetches a fresh copy.
+// Soft purges require surrogate keys.
// https://docs.fastly.com/en/guides/soft-purges
// https://docs.fastly.com/en/guides/getting-started-with-surrogate-keys
-// What the header needs to be called for Fastly to recognize it.
+// Fastly reads surrogate keys from this response header.
const KEY = 'surrogate-key'
export const SURROGATE_ENUMS = {
@@ -59,16 +56,14 @@ export function makeLanguageSurrogateKey(langCode?: string) {
return `language:${langCode}`
}
-// Build the fine-grained surrogate keys for a content response.
-// A content page is exactly one of each axis, so ~5 keys per page, well under
-// Fastly's 16 KB Surrogate-Key header limit:
-//
-// language:<code> (also emitted for non-content responses)
-// product:<top-level dir> e.g. product:actions (~36)
-// version:<short release slug> e.g. version:ghes-3.14 (~7-8)
-// product:<x>,language:<y> compound, for targeted translation purges
-// language:<code>,path:<path> compound, one key per source page, all versions
-//
+// Content responses get about five keys, one per purge axis,
+// below Fastly's 16 KB header limit.
+// Shapes include language:<code>, product:<top-level-dir>, version:<short-release-slug>,
+// product:<product>,language:<code>, and language:<code>,path:<source-path>.
+// language:<code> also appears on non-content responses.
+// product:<product>,language:<code> targets translation purges.
+// language:<code>,path:<source-path> covers one source page across all versions.
+// Each response emits at most one product key and at most one version key.
export function makeContentSurrogateKeys({
langCode,
productId,
@@ -97,20 +92,19 @@ export function makeContentSurrogateKeys({
return keys
}
-// One surrogate key per source page, e.g. `language:en,path:actions/foo.md`,
-// covering every version-URL of the page. A pure function of language and
-// relativePath so the purge job can rebuild the same key from a changed file's
-// path. Language-scoped so an English deploy doesn't evict translations. Returns
-// undefined for non-content responses.
+// Page surrogate keys cover every version URL for one source page.
+// Example: language:en,path:actions/foo.md.
+// The purge job rebuilds them from changed file paths.
+// Language scoping avoids evicting translations on English deploys.
+// Missing language or path returns undefined for non-content responses.
export function makePageSurrogateKey(langCode?: string, relativePath?: string): string | undefined {
if (!langCode || !relativePath) return undefined
return `language:${langCode},path:${relativePath}`
}
-// Derive the product id for the `product:` surrogate key from a content page's
-// path. The top-level content directory is the product id (mirrors
-// Page.parentProductId), e.g. `actions`. Returns undefined for non-content
-// responses and the top-level homepage (`content/index.md`).
+// Product surrogate keys use the top-level content directory, mirroring Page.parentProductId.
+// Example: actions.
+// Non-content responses and the top-level homepage return undefined.
function productSurrogateId(page?: Page): string | undefined {
const relativePath = page?.relativePath
if (!relativePath) return undefined
@@ -119,10 +113,9 @@ function productSurrogateId(page?: Page): string | undefined {
return id
}
-// Derive the short release slug for the `version:` surrogate key, e.g. `fpt`,
-// `ghec`, `ghes-3.14`. Numbered releases (GHES) get the release appended so a
-// version-scoped purge can target a single release; unnumbered plans use the
-// plain short name.
+// Version surrogate keys use the short name.
+// Numbered GitHub Enterprise Server releases append currentRelease for single-release purges.
+// Unnumbered plans use the short name alone.
function versionSurrogateKey(versionObj?: Version): string | undefined {
if (!versionObj) return undefined
return versionObj.hasNumberedReleases
diff --git a/src/frame/middleware/trailing-slashes.ts b/src/frame/middleware/trailing-slashes.ts
index 53e34ac1856d..cd80572031b9 100644
--- a/src/frame/middleware/trailing-slashes.ts
+++ b/src/frame/middleware/trailing-slashes.ts
@@ -15,7 +15,8 @@ export default function trailingSlashes(req: ExtendedRequest, res: Response, nex
if (split.length) {
url += `?${split.join('?')}`
}
- url = url.replace(/\/+/g, '/') // Prevent multiple slashes
+ // Collapse repeated slashes so the redirect points to one canonical URL.
+ url = url.replace(/\/+/g, '/')
defaultCacheControl(res)
return res.safeRedirect(301, url)
}
diff --git a/src/frame/middleware/url-decode.ts b/src/frame/middleware/url-decode.ts
index 7e49a5e3f86f..ae76a8774b6d 100644
--- a/src/frame/middleware/url-decode.ts
+++ b/src/frame/middleware/url-decode.ts
@@ -1,7 +1,7 @@
import type { NextFunction, Response } from 'express'
import type { ExtendedRequest } from '@/types'
-// Decodes URL-encoded @ symbols anywhere in the URL.
+// Decode URL-encoded @ symbols anywhere in the URL.
// SharePoint and other systems encode @ as %40, which breaks our versioned
// URLs like /en/enterprise-cloud@latest.
export default function urlDecode(req: ExtendedRequest, res: Response, next: NextFunction) {
@@ -16,7 +16,6 @@ export default function urlDecode(req: ExtendedRequest, res: Response, next: Nex
req.url = decodedUrl
return next()
} catch {
- // If decoding fails for any reason, continue with original URL
return next()
}
}
diff --git a/src/frame/pages/app.tsx b/src/frame/pages/app.tsx
index 386c5c496705..4ee1f221fcfe 100644
--- a/src/frame/pages/app.tsx
+++ b/src/frame/pages/app.tsx
@@ -45,11 +45,9 @@ const stagingNames = new Set([
'yew',
])
+// Cache-busting prefixes need any cb-number so Fastly assigns the manual surrogate key.
+// Change the cb number when the image changes, so browsers and the CDN miss the old URL.
function getFaviconHref(stagingName?: string) {
- // The number in these "/cb-xxxxx" prefixes does not matter, it just has to be
- // present. It marks the URL as checksummed, which gets it a manual Fastly
- // surrogate key so a production deploy does not purge it.
- // If you edit these images on disk, change the numbers.
if (stagingName) {
return `/assets/cb-346/images/site/evergreens/${stagingName}.png`
}
@@ -110,12 +108,7 @@ const MyApp = ({ Component, pageProps, languagesContext, stagingName }: MyAppPro
dayScheme={theme.component.dayScheme}
nightScheme={theme.component.nightScheme}
>
- {/*
- Primer Brand ThemeProvider, nested so migrated @primer/react-brand
- components receive brand theme context during the Docs 2026 migration
- (github/docs-engineering#5879). Runs alongside the @primer/react
- ThemeProvider above while the component-by-component swap is in progress.
- */}
+ {/* @primer/react-brand context lets Brand components coexist with @primer/react. */}
<BrandThemeProvider>
<LanguagesContext.Provider value={languagesContext}>
<SharedUIContextProvider>
@@ -131,30 +124,22 @@ const MyApp = ({ Component, pageProps, languagesContext, stagingName }: MyAppPro
MyApp.getInitialProps = async (appContext: AppContext) => {
const { ctx } = appContext
- // calls page's `getInitialProps` and fills `appProps.pageProps`
const appProps = await App.getInitialProps(appContext)
const req = ctx.req as unknown as ExtendedRequest
- // Have to define the type manually here because `req.context.languages`
- // comes from Node JS and is not type-aware.
const languagesContext: LanguagesContextT = {
languages: {},
}
- // If we're rendering certain 404 error pages, the middleware might not
- // yet have contextualized the `context.languages`. So omit this
- // context mutation and live without it.
- // Note, `req` will be undefined if this is the client-side rendering
- // of a 500 page ("Ooops! It looks like something went wrong.")
+ // Some 404 renders lack req.context.languages.
if (req?.context?.languages) {
const languageEntries = Object.entries(req.context.languages as Record<string, LanguageItem>)
for (const [langCode, langObj] of languageEntries) {
- // Only pick out the keys we actually need
languagesContext.languages[langCode] = {
name: langObj.name,
code: langObj.code,
}
- // The `hreflang` is used for the `<link rel="alternate">` tags.
+ // hreflang drives alternate-language link tags.
if (langObj.hreflang && langObj.hreflang !== langObj.code) {
languagesContext.languages[langCode].hreflang = langObj.hreflang
}
diff --git a/src/frame/start-server.ts b/src/frame/start-server.ts
index aa7021dd454a..ec5f6620269e 100644
--- a/src/frame/start-server.ts
+++ b/src/frame/start-server.ts
@@ -1,6 +1,5 @@
-// IMPORTANT: OTel tracing MUST be the first import. It patches Node.js
-// built-ins (http, etc.) at load time via auto-instrumentation.
-// Moving this after any framework import will silently break tracing.
+// Import tracing before framework code so auto-instrumentation can patch Node.js built-ins.
+// Moving it later silently breaks OTel tracing.
import '@/observability/lib/tracing'
import http from 'http'
@@ -44,17 +43,13 @@ async function checkPortAvailability() {
}
}
+// startServer warms the idempotent server cache before listen, so development restarts do not
+// block the first page refresh.
+// The SIGTERM timer forces exit after 25s because the preStop hook sleeps 5s and Kubernetes
+// SIGKILLs at 60s, while the deploy controller can time out on old terminating pods.
async function startServer() {
const app = createApp()
- // Warm up as soon as possible.
- // The `warmServer()` function is idempotent and it will soon be used
- // by some middleware, but there's no point in having a started server
- // without this warmed up. Besides, by starting this slow thing now,
- // it can start immediately instead of waiting for the first request
- // to trigger it to warm up. That way, when in development and triggering
- // a `nodemon` restart, there's a good chance the warm up has come some
- // way before you manage to reach for your browser to do a page refresh.
await warmServer([])
// Workaround for https://github.com/expressjs/express/issues/1101
@@ -65,8 +60,7 @@ async function startServer() {
process.once('SIGTERM', () => {
logger.info('Received SIGTERM, beginning graceful shutdown', { pid: process.pid, port })
- // Force-close idle keep-alive sockets so server.close() doesn't hang
- // waiting for them to disconnect naturally.
+ // Force-close idle keep-alive sockets so server.close() does not wait for natural disconnects.
try {
server.closeIdleConnections()
} catch (err) {
@@ -77,11 +71,6 @@ async function startServer() {
logger.info('HTTP server closed')
})
- // If in-flight requests haven't drained within 25s, force exit.
- // Kubernetes sends SIGKILL at terminationGracePeriodSeconds (60s),
- // but the deploy controller may time out before that if an old pod
- // stays in "Terminating" state too long. The preStop hook sleeps 5s,
- // so 25s here keeps total shutdown well under the 60s grace period.
setTimeout(() => {
logger.warn('Graceful shutdown timed out, forcing exit')
try {
diff --git a/src/frame/stylesheets/article-link-overrides.scss b/src/frame/stylesheets/article-link-overrides.scss
index 47ea20966506..d3519c2ee5dc 100644
--- a/src/frame/stylesheets/article-link-overrides.scss
+++ b/src/frame/stylesheets/article-link-overrides.scss
@@ -1,49 +1,29 @@
-// Docs 2026 article-body link colour, overriding @primer/css's base `a` rule.
+// Docs 2026 article-body links need Brand blue instead of @primer/css accent blue.
//
-// @primer/css/base/base.scss sets
-// a { color: var(--fgColor-accent, var(--color-accent-fg)); }
-// `--fgColor-accent` is defined nowhere in this app except inside a
-// `forced-colors` block, so every link falls through to `--color-accent-fg` and
-// paints Primer's accent blue — #0969da light / #58a6ff dark. That is still the
-// OLD design system's accent; brand ships its own link blue, and the article
-// body is the most visible place the difference shows.
+// @primer/css/base/base.scss sets a to Primer accent blue through --fgColor-accent:
+// #0969da light and #4493f8 dark. Article body links need Brand link blue instead.
//
-// Scoped to `#article-contents[data-article-body] .markdown-body`, matching the
-// scope src/content-render/stylesheets/article-section-framing.scss uses for the
-// article body. All three parts are load-bearing: this stylesheet is global, so
-// a bare `a` rule would repaint the header, sidebar, landings, search and footer
-// as well; `.markdown-body` on its own would still catch the REST / GraphQL /
-// webhook pages that reuse the class; and the id on its own is not enough
-// either, because AutomatedPage renders the same `#article-contents` wrapper for
-// the GraphQL, webhook, audit-log and github-apps pages. The data attribute is
-// set only by ArticlePage and TocLanding.
+// The selector must match src/content-render/stylesheets/article-section-framing.scss:
+// #article-contents[data-article-body] .markdown-body. A bare a rule would repaint the header,
+// sidebar, landings, search, and footer. .markdown-body would also catch REST, GraphQL, and
+// webhook pages. #article-contents would also catch AutomatedPage GraphQL, webhook, audit-log,
+// and github-apps pages. ArticlePage and TocLanding set data-article-body.
#article-contents[data-article-body] .markdown-body {
- // `--brand-color-text-link-*` are the semantic tokens that brand's own
- // InlineLink component aliases into `--brand-InlineLink-color-*`. Using the
- // semantic pair keeps this independent of any ancestor that re-maps the
- // component token — breadcrumbs-overrides.scss does exactly that.
+ // Use --brand-color-text-link-* semantic tokens because breadcrumbs-overrides.scss remaps
+ // --brand-InlineLink-color-* for breadcrumbs.
//
- // Three exclusions, all because this selector outweighs the rules that
- // currently keep those anchors uncoloured:
- // - `[href]` — @primer/css holds `.markdown-body a:not([href])` at
- // `color: inherit`, for the bare named anchors markdown emits.
- // - `:not(.heading-link)` — heading anchors wrap the entire heading text,
- // and headings.scss holds them at `color: unset`.
- // - `:not(.btn)` — CTA buttons in content are plain anchors carrying
- // @primer/css's button classes (`<a class="btn btn-primary">`), so they
- // match this rule too. `.btn-primary`'s own `color` is only (0,1,0)
- // against this selector's (1,4,1), so without the exclusion the label
- // painted brand link-blue on the green button — #005dd5 on #1f883d is
- // 1.31:1, well under the 4.5:1 WCAG AA floor
- // (github/technical-content#7679). Excluding `.btn`
- // hands every button variant back to its own Primer colour tokens.
+ // Exclude anchors that this selector would otherwise override:
+ // a[href] preserves @primer/css .markdown-body a:not([href]) named anchors at color: inherit.
+ // :not(.heading-link) preserves headings.scss, which keeps heading text at color: unset.
+ // :not(.btn) preserves CTA button labels. A .btn-primary label would be #005dd5 on #1f883d,
+ // 1.31:1 contrast, below the 4.5:1 WCAG AA floor.
a[href]:not(.heading-link):not(.btn) {
- // Fallback literals are brand's LIGHT values, not Primer's.
+ // Fallback literals apply only when Brand tokens are undefined.
color: var(--brand-color-text-link-rest, #005dd5);
- // Pressed is brand's only other link colour state. It defines no `:visited`
- // colour, and InlineLink's hover thickens the underline rather than changing
- // colour, so @primer/css's hover underline is left alone.
+ // Pressed is Brand's only other link color state.
+ // Brand has no visited color, and InlineLink only thickens hover underlines.
+ // Leave @primer/css hover behavior unchanged.
&:active {
color: var(--brand-color-text-link-pressed, #002f7a);
}
diff --git a/src/frame/stylesheets/breadcrumbs-overrides.scss b/src/frame/stylesheets/breadcrumbs-overrides.scss
index 9f04809032d7..743bce5fdb65 100644
--- a/src/frame/stylesheets/breadcrumbs-overrides.scss
+++ b/src/frame/stylesheets/breadcrumbs-overrides.scss
@@ -1,31 +1,21 @@
-// Docs 2026 breadcrumb treatment, overriding @primer/react-brand's Breadcrumbs.
+// Docs 2026 breadcrumbs invert @primer/react-brand default emphasis.
//
-// Brand's `default` variant renders the ancestor crumbs at full strength and
-// MUTES the current page. The design wants the inverse: the pages you are not
-// viewing — and the "/" separators between them — recede, while the page you're
-// on reads at full strength.
+// Brand's default variant gives ancestor crumbs full strength and mutes the current page. The
+// design needs ancestor pages and "/" separators to recede while the current page stays full
+// strength.
//
-// Keyed off the `data-container` attribute rather than a class because brand's
-// Breadcrumbs <nav> discards any className passed to it, so there is no class
-// hook on that element. The element selectors (`nav`, `li`) are here to out-
-// weigh brand's own rules, which are applied through the component's CSS module
-// and can load after this stylesheet — specificity, rather than source order,
-// is what keeps these overrides winning.
+// Use data-container because Brand Breadcrumbs nav drops className, so no class hook reaches that
+// element. The nav and li selectors raise specificity above Brand CSS modules that can load later.
nav[data-container="breadcrumbs"] {
- // Match the type of the SELECTED doc-tree nav item exactly. Brand already
- // sizes crumbs at 14px/400 (text-size-100) but leaves letter-spacing unset,
- // where the NavList item carries the 100-scale value.
+ // Match the selected doc-tree nav item type: 14px/400 plus 100-scale letter spacing.
letter-spacing: var(--brand-text-letterSpacing-100);
- // Ancestor crumbs (still links) and the separator rules recede. The separator
- // is drawn as a rotated border on `li::after`, so it reads this token rather
- // than `color`.
+ // Ancestor links and separators recede. li::after draws separators as a rotated border.
--brand-InlineLink-color-rest: var(--brand-color-text-muted);
--brand-InlineLink-color-pressed: var(--brand-color-text-muted);
--brand-breadcrumbs-separator-borderColor: var(--brand-color-text-muted);
- // The current page reads at full strength. Brand's default variant explicitly
- // mutes this one, so this needs to outweigh a two-class selector.
+ // The current page needs more specificity than Brand's two-class selector.
li [aria-current="page"] {
color: var(--brand-color-text-default);
}
diff --git a/src/frame/stylesheets/dialog-overrides.scss b/src/frame/stylesheets/dialog-overrides.scss
index 4401dcd0e78d..1f32f8305af5 100644
--- a/src/frame/stylesheets/dialog-overrides.scss
+++ b/src/frame/stylesheets/dialog-overrides.scss
@@ -1,7 +1,7 @@
@import "breakpoint-xxl.scss";
#__primerPortalRoot__ [class*="prc-Dialog-Backdrop"] {
- /* Make sure the dialog backdrop is hidden on large screens */
+ /* The XXL breakpoint below hides the dialog backdrop on large screens. */
display: flex;
visibility: visible;
@@ -11,7 +11,7 @@
}
}
-// Fix z-index for ActionMenu overlays (version picker, etc.) to appear above site header
+// Keep ActionMenu overlays, including the version picker, above the site header.
#__primerPortalRoot__ * {
z-index: 3 !important;
}
diff --git a/src/frame/stylesheets/index.scss b/src/frame/stylesheets/index.scss
index f2e1ea2ed82e..50bc17542340 100644
--- a/src/frame/stylesheets/index.scss
+++ b/src/frame/stylesheets/index.scss
@@ -1,38 +1,32 @@
-@import "@primer/css/color-modes/index.scss"; // Must come first
-@import "@primer/css/core/index.scss"; // Must come second
+@import "@primer/css/color-modes/index.scss"; // Color modes must load before core.
+@import "@primer/css/core/index.scss"; // Core must load before component styles.
-// Primer Primitives functional themes.
+// Primer functional theme tokens bridge @primer/css and @primer/react.
//
-// @primer/css@21 only defines the legacy `--color-*` names (it pins its own
-// nested @primer/primitives@7). @primer/react@38's component CSS, and a lot of
-// our own SCSS, reference the newer `--fgColor-*` / `--bgColor-*` /
-// `--borderColor-*` / `--button-*` names instead — and nothing in this app
-// defined them. An undefined custom property makes the whole declaration
-// invalid at computed-value time, so those rules either dropped out entirely
-// (`border: 1px solid var(--borderColor-default)` painted no border at all) or
-// fell through to a hardcoded light-mode hex that then won in BOTH modes.
-// That is why PRC components rendered light-grey icons in dark mode.
+// @primer/css defines legacy --color-* names, while @primer/react and this SCSS reference newer
+// --fgColor-*, --bgColor-*, --borderColor-*, and --button-* names. Missing custom properties
+// invalidate whole declarations at computed-value time, which drops rules or falls through to
+// hardcoded light-mode hex values in both modes. Primer React components then render light-grey
+// icons in dark mode.
//
-// Scoped by [data-color-mode]/[data-*-theme] exactly like the @primer/css
-// themes above, so only the active theme's block applies. Limited to the four
-// themes `SupportedTheme` actually allows (see src/color-schemes).
+// Scope these imports by [data-color-mode] and [data-*-theme] like @primer/css themes, so only
+// the active theme block applies. Limit them to the four themes SupportedTheme allows in
+// src/color-schemes.
@import "@primer/primitives/dist/css/functional/themes/light.css";
@import "@primer/primitives/dist/css/functional/themes/dark.css";
@import "@primer/primitives/dist/css/functional/themes/dark-dimmed.css";
@import "@primer/primitives/dist/css/functional/themes/dark-high-contrast.css";
-// Primer components
@import "@primer/css/markdown/index.scss";
@import "@primer/css/labels/index.scss";
@import "@primer/css/alerts/index.scss";
@import "@primer/css/popover/index.scss";
-// Primer Brand design system (Docs 2026 migration — github/docs-engineering#5879).
+// Primer Brand design system for the Docs 2026 migration.
// Loaded alongside @primer/css during the incremental component-by-component swap.
@import "@primer/react-brand/lib/css/main.css";
-// Registers the Mona Sans / Hubot Sans @font-face rules (+ metric-adjusted
-// fallbacks) that back the brand `--brand-*-fontFamily` tokens. Without this,
-// those tokens silently fall back to the system font stack.
+// Registers the Mona Sans and Hubot Sans font-face rules plus metric-adjusted fallbacks that back
+// the Brand fontFamily tokens. Without this, those tokens silently fall back to the system stack.
@import "@primer/react-brand/fonts/fonts.css";
@import "headings.scss";
@@ -45,58 +39,39 @@
@import "src/content-render/stylesheets/index.scss";
@import "src/links/stylesheets/hover-card.scss";
-// For primer Spinners and other animated components
@import "@primer/primitives/dist/css/base/motion/motion.css";
-// Docs 2026: Primer Brand owns the page canvas.
+// Primer Brand owns the page canvas.
//
-// `@primer/css/base/native-colors.scss` paints both `body` and *every*
-// `[data-color-mode]` element from the Primer Component palette:
+// @primer/css/base/native-colors.scss paints body and every [data-color-mode] element from the
+// Primer Component palette. @primer/react ThemeProvider renders a wrapper div with
+// data-color-mode, while src/color-schemes/components/BrandThemeProvider.tsx does not, so that
+// wrapper would paint Primer's canvas. In dark mode that canvas is #0d1117, while migrated Brand
+// surfaces sit on #000000 or #0f1511. #0f1511 on #0d1117 is 1.02:1.
//
-// [data-color-mode] {
-// color: var(--fgColor-default, var(--color-fg-default));
-// background-color: var(--bgColor-default, var(--color-canvas-default));
-// }
+// Repoint the root canvas at Brand so migrated surfaces read together. Primer-palette subtle fills
+// #161b22 and borders #30363d remain visible above true black.
//
-// @primer/react's `ThemeProvider` renders a real wrapping `<div data-color-mode>`
-// (brand's no longer does; see src/color-schemes/components/BrandThemeProvider.tsx),
-// so it matched that selector and painted itself Primer's canvas. In dark mode
-// that is #0d1117 — a
-// blue-tinted charcoal — while every surface migrated to Brand tokens sits on
-// Brand's true black (#000000) or its green-tinted near-black (#0f1511). The
-// result was up to three different "blacks" stacked on one page, and fills
-// meant to read as a lift above the page instead read as an invisible dip below
-// it (#0f1511 on #0d1117 is 1.02:1).
-//
-// Repointing the canvas at Brand is what makes the migrated surfaces cohere.
-// Primer-palette components layered on top still read correctly, because their
-// subtle fills (#161b22) and borders (#30363d) become lifts above true black
-// rather than clashing steps beside it.
-//
-// The canvas is decided at the ROOT, and only at the root. `<html>` is the one
-// element whose `data-color-mode` is correct before first paint: colorModeScript
-// (src/color-schemes/lib/color-mode-script.ts) stamps it from the cookie
-// synchronously in <head>. The SSR markup cannot carry the user's real mode,
-// because that HTML is shared-cacheable in the CDN and must be identical for
-// every request.
+// Only the root decides the canvas. html carries the correct data-color-mode before first paint
+// because src/color-schemes/lib/color-mode-script.ts stamps it from the cookie in head. SSR cannot
+// carry the user's mode because shared CDN HTML must stay identical for every request.
html[data-color-mode],
html[data-color-mode] body {
background-color: var(--brand-color-canvas-default);
color: var(--brand-color-text-default);
}
-// ...and every NESTED [data-color-mode] wrapper stays transparent so the root
-// canvas shows through — @primer/react's ThemeProvider still renders one. Never
-// a `--brand-*` token here: a nested wrapper re-declares brand's palette and
-// would paint its own mode, not the page's. `:not(html)` adds html's (0,0,1) to
-// beat @primer/css's `[data-color-mode]` (0,1,0).
+// Nested [data-color-mode] wrappers stay transparent so the root canvas shows through.
+// @primer/react ThemeProvider still renders one. Never use a --brand-* token here: a nested
+// wrapper re-declares Brand's palette and would paint its own mode instead of the page mode.
+// :not(html) adds html specificity to beat @primer/css [data-color-mode] at 0,1,0.
[data-color-mode]:not(html) {
background-color: transparent;
color: inherit;
}
-// No-JS fallback, not dead code: without the pre-paint script <html> keeps the
-// SSR `auto` default, which @primer/primitives honours and brand does not.
+// No-JS fallback: without the pre-paint script, html keeps the SSR auto default, which
+// @primer/primitives honors and Brand does not.
@media (prefers-color-scheme: dark) {
html[data-color-mode="auto"][data-dark-theme*="dark"] {
--brand-color-canvas-default: var(--base-color-scale-black-0);
@@ -118,24 +93,19 @@ html[data-color-mode] body {
}
}
-// Docs 2026: links use Brand's link colour.
+// Site-wide links use Brand link blue.
//
-// `@primer/css/base/base.scss` sets `a { color: var(--fgColor-accent, …) }` —
-// Primer's blue (#0969da light / #4493f8 dark). Brand's link blue is a
-// different value (#0055d5 light / #a2daff dark) and is what the migrated
-// surfaces are designed around. `.markdown-body` does not set its own anchor
-// colour, so prose links inherit this too.
+// @primer/css/base/base.scss sets a color to var(--fgColor-accent, ...) values: #0969da light and
+// #4493f8 dark. Brand link blue is #0055d5 light and #a2daff dark. Migrated surfaces use Brand
+// colors, and .markdown-body prose links inherit this rule.
//
-// Specificity is deliberately left at (0,0,1) to exactly match the rule this
-// replaces. Anything more specific — `a[href]`, say — would start winning
-// against component classes like `.prc-Button-*` (0,1,0) and repaint PRC
-// buttons that happen to render as anchors. This is a value swap, not a
-// cascade change; primer's own `a:not([href])` carve-outs still apply.
+// Keep specificity at 0,0,1 to match the rule this replaces. More specificity, such as a[href],
+// would win against component classes like .prc-Button-* at 0,1,0 and repaint PRC buttons that
+// render as anchors. This swaps the value without changing the cascade, so @primer/css
+// a:not([href]) carve-outs still apply.
//
-// article-link-overrides.scss layers a much more specific rule over the article
-// body for the same token. That is not redundant: it adds the `:active` pressed
-// state and deliberately exempts `.heading-link` and bare named anchors. This
-// rule is the site-wide base; that one is the article body's specialisation.
+// article-link-overrides.scss layers a more specific rule over the article body for the same token.
+// It adds the :active pressed state and exempts .heading-link, .btn, and bare named anchors.
a {
color: var(--brand-color-text-link-rest);
}
diff --git a/src/frame/stylesheets/scroll-top.scss b/src/frame/stylesheets/scroll-top.scss
index 4645b5ff64eb..f7c3f93d1a1e 100644
--- a/src/frame/stylesheets/scroll-top.scss
+++ b/src/frame/stylesheets/scroll-top.scss
@@ -1,10 +1,9 @@
@import "src/frame/stylesheets/breakpoint-xxl.scss";
-// Mirrors Brand's SubdomainNavBar height so every sticky offset tracks the real
-// header. Brand defines that height in rem -- `--base-size-64` (4rem), reduced by
-// `--base-size-8` (0.5rem) below its `medium` breakpoint of 47.99rem -- so these
-// must be rem too. A px value with a px breakpoint silently drifts from the
-// actual header for any reader whose browser default font size is not 16px.
+// Brand SubdomainNavBar height uses rem, so the header portion of sticky offsets must use rem too.
+// Brand sets --base-size-64 at 4rem and subtracts --base-size-8, 0.5rem, below its medium
+// breakpoint of 47.99rem. A px value or px breakpoint drifts when readers change the browser
+// default font size.
:root {
--docs-header-height: 3.5rem;
@@ -21,6 +20,6 @@
@include breakpoint-xxl {
scroll-margin-top: calc(
var(--docs-header-height) + 44px
- ) !important; // Header + secondary bar
+ ) !important; // Include the secondary bar below the header.
}
}
diff --git a/src/frame/stylesheets/utilities.scss b/src/frame/stylesheets/utilities.scss
index 38d550bc3949..5bf4343df673 100644
--- a/src/frame/stylesheets/utilities.scss
+++ b/src/frame/stylesheets/utilities.scss
@@ -37,7 +37,7 @@
width: 1px;
}
-// For the screenreader
+// Screen readers and keyboard users need a visible skip link on focus.
.skip-button {
width: auto;
height: auto;
@@ -56,7 +56,7 @@
}
}
-// used to help prevent overlapping main content and the minitoc sidebar
+// Avoid overlapping main content and the mini TOC sidebar at XXL widths.
.d-xxl-block {
@include breakpoint-xxl {
display: block !important;
diff --git a/src/frame/tests/content.ts b/src/frame/tests/content.ts
index 0e145e55e82e..31e3efc9cc9f 100644
--- a/src/frame/tests/content.ts
+++ b/src/frame/tests/content.ts
@@ -36,7 +36,7 @@ describe('content files', () => {
const orphanedFiles = contentFiles.filter((file) => !relativeFiles.includes(file))
- // Filter out intentional test fixture files that are meant to be orphaned
+ // These fixture files intentionally stay outside the tree.
const allowedOrphanedFiles = [
path.join(contentDir, 'article-one.md'),
path.join(contentDir, 'article-two.md'),
diff --git a/src/frame/tests/fetch-utils.test.ts b/src/frame/tests/fetch-utils.test.ts
index c98addc7aa7a..2bdfb82ef29f 100644
--- a/src/frame/tests/fetch-utils.test.ts
+++ b/src/frame/tests/fetch-utils.test.ts
@@ -85,8 +85,7 @@ describe('fetchWithRetry ttfb timeout mode', () => {
await fetchWithRetry('https://example.test/big', {}, { timeout: 10, timeoutMode: 'ttfb' })
- // Wait well past the TTFB deadline; the timer must have been cleared so the
- // signal stays unaborted and a subsequent body read wouldn't be cut off.
+ // Wait past the TTFB deadline to prove response resolution cleared the timer.
await new Promise((resolve) => setTimeout(resolve, 40))
expect(capturedSignal?.aborted).toBe(false)
expect(statsdIncrement).not.toHaveBeenCalled()
@@ -197,9 +196,7 @@ describe('fetchStream timeout mode', () => {
await fetchStream('https://example.test/stream', {}, { timeout: 10, throwHttpErrors: false })
- // A streaming caller reads the body well past the connect deadline. With the
- // ttfb default the timer is cleared on response-resolve, so the signal stays
- // unaborted and a long-running reader.read() loop won't be cut off.
+ // Wait past the TTFB deadline to prove response resolution cleared the default timer.
await new Promise((resolve) => setTimeout(resolve, 40))
expect(capturedSignal?.aborted).toBe(false)
expect(statsdIncrement).not.toHaveBeenCalled()
diff --git a/src/frame/tests/find-page-middleware.ts b/src/frame/tests/find-page-middleware.ts
index ab42f6d23883..9aa21f4047a5 100644
--- a/src/frame/tests/find-page-middleware.ts
+++ b/src/frame/tests/find-page-middleware.ts
@@ -127,8 +127,7 @@ describe('find page middleware', () => {
})
test("will 404 if the request version doesn't match the page", async () => {
- // The 'versions:' frontmatter on 'page-with-redirects.md' does
- // not include ghes. So this'll eventually 404.
+ // page-with-redirects.md excludes GHES, so enterprise-server@latest eventually 404s.
const [req, res] = makeRequestResponse('/en/page-with-redirects', 'enterprise-server@latest')
const page = await Page.init({
relativePath: 'page-with-redirects.md',
diff --git a/src/frame/tests/get-remote-json.ts b/src/frame/tests/get-remote-json.ts
index 5f1270ef0b09..87e0e639ca0e 100644
--- a/src/frame/tests/get-remote-json.ts
+++ b/src/frame/tests/get-remote-json.ts
@@ -7,8 +7,7 @@ import nock from 'nock'
import getRemoteJSON, { cache } from '@/frame/lib/get-remote-json'
-// Covers the in-memory cache, and the fallback to the disk cache when memory
-// misses.
+// Covers in-memory caching and disk-cache fallback after a memory miss.
describe('getRemoteJSON', () => {
const envVarValueBefore = process.env.GET_REMOTE_JSON_DISK_CACHE_ROOT
@@ -34,8 +33,7 @@ describe('getRemoteJSON', () => {
const data = await getRemoteJSON(url, {})
expect((data as Record<string, unknown>).foo).toBe('bar')
expect(cache.get(url)).toBeTruthy()
- // Second time, despite not setting up a second nock(), will work
- // because it can use memory now.
+ // A second network request would fail unless getRemoteJSON uses the memory cache.
const data2 = await getRemoteJSON(url, {})
expect((data2 as Record<string, unknown>).foo).toBe('bar')
expect(cache.get(url)).toBeTruthy()
@@ -50,9 +48,7 @@ describe('getRemoteJSON', () => {
expect(cache.get(url)).toBeTruthy()
cache.delete(url)
- // This time, the nock won't fail despite not using `.persist()`.
- // That means it didn't need the network because it was able to
- // use the disk cache.
+ // A second network request would fail unless getRemoteJSON uses the disk cache.
const data2 = await getRemoteJSON(url, {})
expect((data2 as Record<string, unknown>).cool).toBe(true)
})
@@ -70,8 +66,7 @@ describe('getRemoteJSON', () => {
}
cache.delete(url)
- // If we don't do this, nock will fail because a second network
- // request became necessary.
+ // A second nock response lets getRemoteJSON recover after the corrupted disk cache misses.
nock(origin).get(pathname).reply(200, { cool: true })
const data = await getRemoteJSON(url, {})
@@ -92,8 +87,7 @@ describe('getRemoteJSON', () => {
}
cache.delete(url)
- // If we don't do this, nock will fail because a second network
- // request became necessary.
+ // A second nock response lets getRemoteJSON recover after the corrupted disk cache misses.
nock(origin).get(pathname).reply(200, { cool: true })
const data = await getRemoteJSON(url, {})
diff --git a/src/frame/tests/manifest.ts b/src/frame/tests/manifest.ts
index 4582d1087d3f..88d5d1211dbd 100644
--- a/src/frame/tests/manifest.ts
+++ b/src/frame/tests/manifest.ts
@@ -26,7 +26,7 @@ describe('manifest', () => {
const res = await get(url)
expect(res.statusCode).toBe(200)
- // Check that it can be cached at the CDN
+ // CDN caching must not set cookies and must include the no-language surrogate key.
expect(res.headers['set-cookie']).toBeUndefined()
expect(res.headers['cache-control']).toContain('public')
expect(res.headers['cache-control']).toMatch(/max-age=[1-9]/)
@@ -45,7 +45,7 @@ describe('manifest', () => {
const iconRes = await get(icon.src, { responseType: 'buffer' })
expect(iconRes.statusCode).toBe(200)
expect(iconRes.headers['content-type']).toBe(icon.type)
- // The `sizes` should match the payload
+ // sizes must match the image payload.
const image = sharp(iconRes.body)
const [width, height] = icon.sizes.split('x').map((s) => parseInt(s))
const dimensions = await image.metadata()
diff --git a/src/frame/tests/mini-toc-items.ts b/src/frame/tests/mini-toc-items.ts
index 3b43d011f62f..a8ea0eead14b 100644
--- a/src/frame/tests/mini-toc-items.ts
+++ b/src/frame/tests/mini-toc-items.ts
@@ -28,18 +28,7 @@ describe('buildMiniTocFromCollected', () => {
expect(tocItems[0].items?.length).toBe(3)
})
- /**
- * Mock scenario from: /en/rest/reference/apps
- * The TOC starts out with lower importance headers that aren't nested in
- * higher importance headers
- *
- * 3
- * 3
- * 2
- * 3
- * 2
- * 3
- */
+ // /en/rest/reference/apps begins with unnested levels 3, 3, then continues 2, 3, 2, 3.
test('creates toc that starts with lower importance headers', () => {
const collected = [
heading('section-1-A', 3),
@@ -54,8 +43,7 @@ describe('buildMiniTocFromCollected', () => {
expect(tocItems[3].items?.length).toBe(1)
})
- // Mock scenario from:
- // /en/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization
+ // Scenario from: /en/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization
test('creates empty toc', () => {
const tocItems = buildMiniTocFromCollected([], 3)
expect(tocItems.length).toBe(0)
diff --git a/src/frame/tests/non-child-pages-resolution.test.ts b/src/frame/tests/non-child-pages-resolution.test.ts
index 47fe3c6fd6e9..ec1bb1fc841b 100644
--- a/src/frame/tests/non-child-pages-resolution.test.ts
+++ b/src/frame/tests/non-child-pages-resolution.test.ts
@@ -4,13 +4,11 @@ import fs from 'fs'
const ROOT = path.resolve(__dirname, '../../..')
-// Tests for non-child page resolution: a `/content/` prefix in children
-// frontmatter resolves to an absolute content path, which is what lets a page
-// pull in a directory or article from another product.
+// Tests for non-child page resolution: /content/ in children frontmatter resolves to an absolute
+// content path, so a page can pull in a directory or article from another product.
//
-// Note this file imports no production code. The behaviour tests reimplement
-// logic from create-tree.ts and current-product-tree.ts, and the rest only check
-// that fixture files exist, so none of it exercises the real resolution path.
+// This file imports no production code. Behavior tests reimplement logic from create-tree.ts and
+// current-product-tree.ts, and the rest only check fixtures, so none exercises the real path.
describe('Non-child page resolution', () => {
describe('/content/ prefix in children frontmatter', () => {
@@ -34,7 +32,6 @@ describe('Non-child page resolution', () => {
const basePath = '/Users/test/docs-internal/content'
const child = '/content/actions/workflows'
- // Simulate the logic from create-tree.ts
let childPath: string
if (child.startsWith('/content/')) {
const absoluteChildPath = child.slice('/content/'.length)
@@ -50,7 +47,6 @@ describe('Non-child page resolution', () => {
const basePath = '/Users/test/docs-internal/content'
const child = '/content/get-started/foo/bar'
- // Simulate the logic from create-tree.ts
let childPath: string
if (child.startsWith('/content/')) {
const absoluteChildPath = child.slice('/content/'.length)
@@ -66,7 +62,6 @@ describe('Non-child page resolution', () => {
const originalPath = '/Users/test/docs-internal/content/get-started'
const child = '/local-child'
- // Simulate the logic from create-tree.ts
let childPath: string
if (child.startsWith('/content/')) {
const absoluteChildPath = child.slice('/content/'.length)
@@ -143,8 +138,7 @@ describe('Non-child page resolution', () => {
describe('translation behavior', () => {
test('cross-product children paths are language-agnostic', () => {
- // The /content/ prefix paths should work regardless of the current language
- // The actual translation is handled by the page loading system
+ // Translation happens after /content/ cross-product path resolution.
const child = '/content/actions/using-workflows/storing-workflow-data-as-artifacts'
expect(child.startsWith('/content/')).toBe(true)
@@ -152,8 +146,7 @@ describe('Non-child page resolution', () => {
})
test('resolved paths use content directory, not translations', () => {
- // Cross-product children are resolved from the main content directory
- // Translations are handled separately by the page rendering system
+ // Cross-product children resolve from the main content directory before translations apply.
const basePath = '/Users/test/docs-internal/content'
const child = '/content/actions/workflows'
@@ -165,7 +158,6 @@ describe('Non-child page resolution', () => {
describe('crossProductChild flag', () => {
test('flag is set for /content/ prefix paths', () => {
- // Simulate the logic from create-tree.ts
const child = '/content/actions/workflows'
const isCrossProduct = child.startsWith('/content/')
expect(isCrossProduct).toBe(true)
@@ -178,7 +170,6 @@ describe('Non-child page resolution', () => {
})
test('crossProductChild flag excludes items from sidebar', () => {
- // Simulate the sidebarTree filtering logic
const childPages = [
{ href: '/en/get-started/foo', title: 'Foo', crossProductChild: false },
{ href: '/en/actions/workflows', title: 'Workflows', crossProductChild: true },
@@ -192,11 +183,8 @@ describe('Non-child page resolution', () => {
})
describe('descendant-of-sibling filtering in sidebar', () => {
+ // When a bespoke landing page lists a parent group and its articles, the sidebar drops those articles.
test('filters out children that are descendants of another sibling', () => {
- // Simulate the sidebarTree descendant filtering logic.
- // When a bespoke landing page lists both individual articles and their
- // parent group as children, the individual articles should be filtered out
- // from the sidebar (they appear nested under their parent group instead).
const childPages = [
{
href: '/en/get-started/copilot/add-custom-instructions',
@@ -212,13 +200,11 @@ describe('Non-child page resolution', () => {
(child) => !siblingHrefs.some((sh) => sh !== child.href && child.href.startsWith(`${sh}/`)),
)
- // The two individual articles under /copilot/ should be removed
expect(dedupedChildPages).toHaveLength(2)
expect(dedupedChildPages.map((c) => c.title)).toEqual(['Copilot', 'Actions'])
})
test('does not filter children that are not descendants of any sibling', () => {
- // Normal case: no overlapping paths, nothing should be filtered
const childPages = [
{ href: '/en/get-started/copilot', title: 'Copilot' },
{ href: '/en/get-started/actions', title: 'Actions' },
@@ -234,7 +220,6 @@ describe('Non-child page resolution', () => {
})
test('handles multiple overlapping groups correctly', () => {
- // Multiple groups each with their own individual articles listed
const childPages = [
{ href: '/en/get-started/copilot/article-a', title: 'Article A' },
{ href: '/en/get-started/copilot', title: 'Copilot' },
diff --git a/src/frame/tests/page.ts b/src/frame/tests/page.ts
index bebcd92e1960..7e14641ed98d 100644
--- a/src/frame/tests/page.ts
+++ b/src/frame/tests/page.ts
@@ -23,7 +23,6 @@ const enterpriseServerVersions = Object.keys(allVersions).filter((v) =>
v.startsWith('enterprise-server@'),
)
-// get the `free-pro-team` segment of `free-pro-team@latest`
const nonEnterpriseDefaultPlan = nonEnterpriseDefaultVersion.split('@')[0]
const opts = {
@@ -80,9 +79,7 @@ describe('Page class', () => {
})
describe('page.render(context)', () => {
- // Most of our Liquid versioning tests are in https://github.com/docs/render-content,
- // But they don't have access to our currently supported versions, which we're testing here.
- // This test ensures that this works as expected: {% if enterpriseServerVersions contains currentVersion %}
+ // Test {% if enterpriseServerVersions contains currentVersion %} here; docs/render-content lacks version data.
test('renders the expected Enterprise Server versioned content', async () => {
const page = await Page.init({
relativePath: 'page-versioned-for-all-enterprise-releases.md',
@@ -104,8 +101,7 @@ describe('Page class', () => {
'This text should only render on non-Enterprise',
)
- // change version to the oldest enterprise version, re-render, and test again;
- // the results should be the same
+ // Re-render with the oldest Enterprise Server version; the text must stay the same.
context.currentVersion = `enterprise-server@${enterpriseServerReleases.oldestSupported}`
context.currentPath = `/${context.currentLanguage}/${context.currentVersion}/${page!.relativePath}`
rendered = await page!.render(context)
@@ -117,8 +113,7 @@ describe('Page class', () => {
'This text should only render on non-Enterprise',
)
- // change version to non-enterprise, re-render, and test again;
- // the results should be the opposite
+ // Re-render with the non-enterprise version; the text must invert.
context.currentVersion = nonEnterpriseDefaultVersion
context.currentPath = `/${context.currentLanguage}/${context.currentVersion}/${page!.relativePath}`
rendered = await page!.render(context)
@@ -325,37 +320,17 @@ describe('Page class', () => {
expect(page!.versions.ghes).toBe('*')
})
+ // Feature versions must combine with frontmatter versions so latest GHES remains applicable.
test('feature versions frontmatter', async () => {
- // This fixture file has the frontmatter:
- //
- // versions:
- // fpt: '*'
- // ghes: '*'
- // feature: 'placeholder'
- //
- // and placeholder.yml has:
- //
- // versions:
- // ghes: '<3.0'
- //
- // So we expect to get the versioning from both.
const page = await Page.init({
relativePath: 'feature-versions-frontmatter.md',
basePath: path.join(__dirname, '../../../src/fixtures/fixtures'),
languageCode: 'en',
})
- // Test the raw page data.
expect(page!.versions.fpt).toBe('*')
expect(page!.versions.ghes).toBe('>2.21')
- // Test the resolved versioning, where GHES releases specified in frontmatter and in
- // feature versions are combined (i.e., one doesn't overwrite the other).
- // We can't test that GHES 2.21 is _not_ included here (which it shouldn't be),
- // because lib/get-applicable-versions only returns currently supported versions,
- // so as soon as 2.21 is deprecated, a test for that _not_ to exist will not be meaningful.
- // But by testing that the _latest_ GHES version is returned, we can ensure that the
- // the frontmatter GHES `*` is not being overwritten by the placeholder's GHES `<3.0`.
expect(page!.applicableVersions.includes('free-pro-team@latest')).toBe(true)
expect(page!.applicableVersions.includes(`enterprise-server@${latest}`)).toBe(true)
expect(page!.applicableVersions.includes('feature')).toBe(false)
@@ -469,7 +444,6 @@ describe('catches errors thrown in Page class', () => {
expect(page!.product).toBe('')
expect(page!.permissions).toBe('')
- // Change to FPT
context.page.version = nonEnterpriseDefaultVersion
context.version = nonEnterpriseDefaultVersion
context.currentPath = '/en/optional/attributes'
diff --git a/src/frame/tests/pages.ts b/src/frame/tests/pages.ts
index 913c49cd5364..7827708918a3 100644
--- a/src/frame/tests/pages.ts
+++ b/src/frame/tests/pages.ts
@@ -57,7 +57,7 @@ describe('pages module', () => {
const redirectToFiles = new Map<string, Set<string>>()
const versionedRedirects: Array<{ path: string; file: string }> = []
- // Page objects have dynamic properties from chain/lodash that aren't fully typed
+ // lodash pick loses the concrete Page fields that the redirect loop needs.
for (const page of englishPages) {
const pageObj = page as Record<string, unknown>
for (const redirect of pageObj.redirect_from as string[]) {
@@ -72,7 +72,7 @@ describe('pages module', () => {
}
}
- // Only consider as duplicate if more than one unique file defines the same redirect
+ // A redirect duplicates only when more than one file defines it.
const duplicates = Array.from(redirectToFiles.entries())
.filter(([, files]) => files.size > 1)
.map(([redirectPath]) => redirectPath)
@@ -93,15 +93,15 @@ describe('pages module', () => {
.filter((page) => {
slugger.reset()
return (
- page.languageCode === 'en' && // only check English
- !page.relativePath.includes('index.md') && // ignore TOCs
- // Page class has dynamic frontmatter properties like 'allowTitleToDifferFromFilename' not in type definition
- !(page as Record<string, unknown>).allowTitleToDifferFromFilename && // ignore docs with override
+ page.languageCode === 'en' && // Only English pages enforce filename-title matching.
+ !page.relativePath.includes('index.md') && // TOCs do not use slugified filenames.
+ // Page has dynamic frontmatter properties that its type omits.
+ !(page as Record<string, unknown>).allowTitleToDifferFromFilename && // Allows override.
slugger.slug(decode(page.title)) !== path.basename(page.relativePath, '.md') &&
slugger.slug(decode(page.shortTitle || '')) !== path.basename(page.relativePath, '.md')
)
})
- // make the output easier to read
+ // Format failures for review.
.map((page) => {
return JSON.stringify(
{
@@ -126,7 +126,7 @@ describe('pages module', () => {
test('every page has valid frontmatter', async () => {
const frontmatterErrors = chain(pages)
- // Page class has dynamic error properties like 'frontmatterErrors' not in type definition
+ // Loaded pages cannot expose frontmatterErrors because Page throws before construction.
.map((page) => (page as Record<string, unknown>).frontmatterErrors)
.filter(Boolean)
.flatten()
@@ -146,7 +146,7 @@ describe('pages module', () => {
const liquidErrors: Array<{ filename: string; error: string }> = []
for (const page of pages) {
- // Page class has dynamic properties like 'raw' markdown not in type definition
+ // raw is not a Page property here, so this loop does not parse page markdown.
const markdown = (page as Record<string, unknown>).raw as string
if (!patterns.hasLiquid.test(markdown)) continue
try {
diff --git a/src/frame/tests/path-utils.ts b/src/frame/tests/path-utils.ts
index 1df7e18f0bba..302b6ec4165e 100644
--- a/src/frame/tests/path-utils.ts
+++ b/src/frame/tests/path-utils.ts
@@ -31,7 +31,7 @@ describe('getProductStringFromPath', () => {
})
test('extracts product from versioned paths', () => {
- // Note: These tests use free-pro-team which is a supported version
+ // free-pro-team@latest is a supported version for these paths.
expect(getProductStringFromPath('/en/free-pro-team@latest/admin/installation')).toBe('admin')
expect(getProductStringFromPath('/free-pro-team@latest/actions/quickstart')).toBe('actions')
expect(getProductStringFromPath('/en/free-pro-team@latest/github/getting-started')).toBe(
@@ -40,7 +40,7 @@ describe('getProductStringFromPath', () => {
})
test('handles enterprise landing pages (version without product)', () => {
- // When a version is present but no product segment follows, return the version string
+ // A version without a product segment resolves to the version string.
expect(getProductStringFromPath('/en/free-pro-team@latest')).toBe('free-pro-team@latest')
expect(getProductStringFromPath('/enterprise-server@latest')).toBe('enterprise-server@latest')
})
diff --git a/src/frame/tests/permalink.ts b/src/frame/tests/permalink.ts
index a1b9e99426de..0f61f784590f 100644
--- a/src/frame/tests/permalink.ts
+++ b/src/frame/tests/permalink.ts
@@ -5,8 +5,7 @@ import enterpriseServerReleases from '@/versions/lib/enterprise-server-releases'
import nonEnterpriseDefaultVersion from '@/versions/lib/non-enterprise-default-version'
import getApplicableVersions from '@/versions/lib/get-applicable-versions'
-// Permalink constructor requires: languageCode, pageVersion, relativePath, title
-// Permalink.derive requires: languageCode, relativePath, title, versions (<- FM prop)
+// Permalink.derive receives applicableVersions after Page merges feature-derived versions.
describe('Permalink class', () => {
test('derives info for unversioned homepage', () => {
diff --git a/src/frame/tests/resolve-carousels.test.ts b/src/frame/tests/resolve-carousels.test.ts
index d185c24c10b6..a7a49d80f1c8 100644
--- a/src/frame/tests/resolve-carousels.test.ts
+++ b/src/frame/tests/resolve-carousels.test.ts
@@ -10,7 +10,7 @@ vi.mock('@/frame/lib/find-page', () => ({
vi.mock('@/content-render/index', () => ({
renderContent: vi.fn((content, _context, options) => {
- // When textOnly is true, return plain text (no HTML wrapper)
+ // textOnly returns plain text so carousel intros stay text-only.
if (options?.textOnly) {
return content
}
@@ -199,7 +199,6 @@ describe('resolveCarousels middleware', () => {
req.context!.pages,
req.context!.redirects,
)
- // Carousel should not be added if all articles are not found
expect(
(req.context!.page as Page & { carousels?: Record<string, ResolvedArticle[]> }).carousels,
).toBeUndefined()
@@ -217,7 +216,6 @@ describe('resolveCarousels middleware', () => {
await resolveCarousels(req, mockRes, mockNext)
- // Should still call next even on error
expect(mockNext).toHaveBeenCalled()
})
@@ -260,7 +258,7 @@ describe('resolveCarousels middleware', () => {
applicableVersions: ['free-pro-team@latest'],
}
- // Mock findPage to fail on first call (content-relative) and succeed on second (page-relative)
+ // First lookup is content-relative; second lookup is page-relative.
mockFindPage.mockReturnValueOnce(undefined).mockReturnValueOnce(testPage as unknown as Page)
const req = createMockRequest({
@@ -318,7 +316,6 @@ describe('resolveCarousels middleware', () => {
req.context!.redirects,
)
- // Verify that the href is a clean path without language/version
expect(
(req.context!.page as Page & { carousels?: Record<string, ResolvedArticle[]> }).carousels,
).toEqual({
@@ -354,7 +351,6 @@ describe('resolveCarousels middleware', () => {
await resolveCarousels(req, mockRes, mockNext)
- // The carousels should not be added since the article isn't available in enterprise-cloud
expect(
(req.context!.page as Page & { carousels?: Record<string, ResolvedArticle[]> }).carousels,
).toBeUndefined()
@@ -377,7 +373,6 @@ describe('resolveCarousels middleware', () => {
await resolveCarousels(req, mockRes, mockNext)
- // Should only have one article, not three duplicates
expect(
(req.context!.page as Page & { carousels?: Record<string, ResolvedArticle[]> }).carousels,
).toEqual({
diff --git a/src/frame/tests/secure-files.ts b/src/frame/tests/secure-files.ts
index 9c760ecd3bc6..bf795fab65f2 100644
--- a/src/frame/tests/secure-files.ts
+++ b/src/frame/tests/secure-files.ts
@@ -2,13 +2,7 @@ import fs from 'fs/promises'
import { describe, expect, test } from 'vitest'
-/*
- * Verify that a list of file paths are present and optionally have a CODEOWNERS entry
- *
- * name: Readable description of file(s)
- * path: Path to secure files (must match entry in CODEOWNERS if code owner required)
- * requiredCodeOwner: (optional) Name of code owner if a code owner is required
- */
+// path must match the CODEOWNERS entry when requiredCodeOwner is set.
type SecureFile = {
name: string
path: string
diff --git a/src/frame/tests/server.ts b/src/frame/tests/server.ts
index f97554d740ca..011911e5c17a 100644
--- a/src/frame/tests/server.ts
+++ b/src/frame/tests/server.ts
@@ -15,10 +15,8 @@ interface Category {
published_articles: string[]
}
-// Parses a Content-Security-Policy header into its directives. Mirrors the
-// behavior of the unmaintained `csp-parse` package it replaces: the policy is
-// lowercased, split on `;`, and each directive's values are returned as a
-// space-joined string, or an empty string when the directive is absent.
+// Match unmaintained csp-parse: lowercase the policy, split directives on semicolons, and join
+// each directive's values with spaces. get() returns '' when a directive is absent.
function parseCsp(policy: string) {
const directives = new Map<string, string>()
for (const part of (policy || '').toLowerCase().split(';')) {
@@ -33,10 +31,8 @@ function parseCsp(policy: string) {
describe('server', () => {
vi.setConfig({ testTimeout: 60 * 1000 })
+ // Warm /en first so a slow first page load fails here instead of in the first test.
beforeAll(async () => {
- // The first page load takes a long time so let's get it out of the way in
- // advance to call out that problem specifically rather than misleadingly
- // attributing it to the first test
const res = await get('/en')
expect(res.statusCode).toBe(200)
})
@@ -46,9 +42,7 @@ describe('server', () => {
expect(res.statusCode).toBe(200)
expect(res.headers['content-length']).toBe('0')
expect(res.body).toBe('')
- // Because the HEAD requests can't be different no matter what's
- // in the request headers (Accept-Language or Cookies)
- // it's safe to let it cache. The only key is the URL.
+ // HEAD responses ignore Accept-Language and Cookies, so URL alone can key the public cache.
expect(res.headers['cache-control']).toContain('public')
expect(res.headers['cache-control']).toMatch(/max-age=\d+/)
})
@@ -115,8 +109,7 @@ describe('server', () => {
expect(keys).toContain('product:get-started')
expect(keys).toContain('product:get-started,language:en')
expect(keys.some((key: string) => /^version:.+/.test(key))).toBe(true)
- // Exact key, not just a pattern, to lock the render side byte-for-byte to what
- // the purge job rebuilds from a changed file path (content/get-started/index.md).
+ // The render key must match the purge key derived from content/get-started/index.md.
expect(keys).toContain('language:en,path:get-started/index.md')
expect(keys).toContain(makePageSurrogateKey('en', 'get-started/index.md'))
expect(keys.length).toBeLessThanOrEqual(6)
@@ -129,8 +122,7 @@ describe('server', () => {
})
test('renders a 404 page', async () => {
- // Important to use the prefix /en/ on the failing URL or else
- // it will render a very basic plain text 404 response.
+ // The /en/ prefix reaches the full 404 page instead of the plain text fallback.
const $ = await getDOM('/en/not-a-real-page', { allow404: true })
expect(($ as unknown as { text(): string }).text()).toContain('Page not found.')
expect($.res.statusCode).toBe(404)
@@ -141,10 +133,7 @@ describe('server', () => {
expect(res.statusCode).toBe(404)
})
- // When using `got()` to send full end-to-end URLs, you can't use
- // URLs like in this test because got will
- // throw `RequestError: URI malformed`.
- // So for now, this test is skipped.
+ // The skip predates the native-fetch helper, which sends this malformed path unchanged.
test.skip('renders a 400 for invalid paths', async () => {
const $ = await getDOM('/en/%7B%')
expect($.res.statusCode).toBe(400)
@@ -153,7 +142,7 @@ describe('server', () => {
test('renders a 500 page when errors are thrown', async () => {
const $ = await getDOM('/_500', { allow500s: true })
expect($('h1').first().text()).toBe('Ooops!')
- // Using type assertion because cheerio v1 types don't include text() on root
+ // Cheerio v1 root types omit text().
expect(
($ as unknown as { text(): string }).text().includes('It looks like something went wrong.'),
).toBe(true)
@@ -177,7 +166,6 @@ describe('server', () => {
expect(res.statusCode).toBe(400)
})
- // see issue 9678
test('does not use cached intros in subcategories', async () => {
let $ = await getDOM(
'/en/get-started/importing-your-projects-to-github/importing-source-code-to-github/importing-a-git-repository-using-the-command-line',
@@ -196,7 +184,7 @@ describe('server', () => {
expect(res.headers['access-control-allow-origin']).toBe('*')
- // Check that it can be cached at the CDN
+ // CDN caching must not set cookies.
expect(res.headers['set-cookie']).toBeUndefined()
expect(res.headers['cache-control']).toContain('public')
expect(res.headers['cache-control']).toMatch(/max-age=[1-9]/)
@@ -213,11 +201,7 @@ describe('server', () => {
describeViaActionsOnly('Early Access articles', () => {
test('have noindex meta tags', async () => {
const allPages = await loadPages()
- // This is what the earlyAccessContext middleware does to get a
- // list of early-access pages for that TOC it displays when
- // viewing /en/early-access in development.
- // Here we're using it to get a least 1 page we can end-to-end
- // test to look at it's meta tags.
+ // Match earlyAccessContext's development TOC input: English hidden early-access articles.
const hiddenPages = allPages.filter(
(page) =>
page.languageCode === 'en' &&
@@ -237,7 +221,7 @@ describe('server', () => {
const res = await get('/articles/deleting-a-team', { followRedirects: false })
expect(res.statusCode).toBe(302)
expect(res.headers['set-cookie']).toBeUndefined()
- // language specific caching
+ // Language-specific redirects must vary by language headers.
expect(res.headers['cache-control']).toContain('public')
expect(res.headers['cache-control']).toMatch(/max-age=[1-9]/)
expect(res.headers.vary).toContain('accept-language')
@@ -249,18 +233,14 @@ describe('server', () => {
expect(res.statusCode).toBe(302)
expect(res.headers.location).toBe('/en')
expect(res.headers['set-cookie']).toBeUndefined()
- // language specific caching
+ // Language-specific redirects must vary by language headers.
expect(res.headers['cache-control']).toContain('public')
expect(res.headers['cache-control']).toMatch(/max-age=[1-9]/)
expect(res.headers.vary).toContain('accept-language')
expect(res.headers.vary).toContain('x-user-language')
})
- // This test exists because in a previous life, our NextJS used to
- // 500 if the 'Accept-Language' header was malformed.
- // We *used* have a custom middleware to cope with this and force a
- // fallback redirect.
- // See internal issue 19909
+ // Invalid Accept-Language once triggered a downstream Next.js 500; this route must redirect.
test('redirects /en if Accept-Language header is malformed', async () => {
const res = await get('/', {
headers: {
@@ -272,7 +252,7 @@ describe('server', () => {
expect(res.statusCode).toBe(302)
expect(res.headers.location).toBe('/en')
expect(res.headers['set-cookie']).toBeUndefined()
- // language specific caching
+ // Language-specific redirects must vary by language headers.
expect(res.headers['cache-control']).toContain('public')
expect(res.headers['cache-control']).toMatch(/max-age=[1-9]/)
expect(res.headers.vary).toContain('accept-language')
@@ -290,7 +270,7 @@ describe('server', () => {
expect(res.statusCode).toBe(302)
expect(res.headers.location).toBe('/en')
expect(res.headers['set-cookie']).toBeUndefined()
- // language specific caching
+ // Language-specific redirects must vary by language headers.
expect(res.headers['cache-control']).toContain('public')
expect(res.headers['cache-control']).toMatch(/max-age=[1-9]/)
expect(res.headers.vary).toContain('accept-language')
@@ -302,7 +282,7 @@ describe('server', () => {
expect(res.statusCode).toBe(302)
expect(res.headers.location.startsWith('/en/')).toBe(true)
expect(res.headers['set-cookie']).toBeUndefined()
- // language specific caching
+ // Language-specific redirects must vary by language headers.
expect(res.headers['cache-control']).toContain('public')
expect(res.headers['cache-control']).toMatch(/max-age=[1-9]/)
expect(res.headers.vary).toContain('accept-language')
@@ -359,7 +339,6 @@ describe('server', () => {
expect(res.statusCode).toBe(200)
expect(res.headers['content-type']).toContain('text/markdown')
expect(res.body).toMatch(/^# .+/)
- // Verify the landing page has content beyond just the title
expect(res.body).toMatch(/\n\n/)
expect(res.body.split('\n').length).toBeGreaterThan(3)
})
@@ -398,10 +377,9 @@ describe('static routes', () => {
expect(res.statusCode).toBe(200)
expect(res.headers['cache-control']).toContain('public')
expect(res.headers['cache-control']).toMatch(/max-age=\d+/)
- // Because static assets shouldn't be setting a cookie.
+ // Static assets must not set cookies.
expect(res.headers['set-cookie']).toBeUndefined()
- // The "Surrogate-Key" header is set so we can do smart invalidation
- // in the Fastly CDN. This needs to be available for static assets too.
+ // Unhashed asset URLs use the generic language surrogate key, not the manual key.
expect(res.headers['surrogate-key']).toBeTruthy()
expect(res.headers.etag).toBeUndefined()
expect(res.headers['last-modified']).toBeTruthy()
@@ -433,7 +411,7 @@ describe('static routes', () => {
expect(res.statusCode).toBe(200)
expect(res.headers['cache-control']).toContain('public')
expect(res.headers['cache-control']).toMatch(/max-age=\d+/)
- // Because static assets shouldn't be setting a cookie.
+ // Static assets must not set cookies.
expect(res.headers['set-cookie']).toBeUndefined()
expect(res.headers.etag).toBeUndefined()
expect(res.headers['last-modified']).toBeTruthy()
@@ -459,8 +437,7 @@ describe('static routes', () => {
'/server.js',
'/.git',
'/.env',
- // Also add paths that aren't at the root. But it doesn't matter
- // which page this is done for so much.
+ // Nested dotfile paths prove product routing cannot expose repo contents.
'/en/billing/.env',
'/en/billing/.env.local',
'/en/pages/.env_sample',
diff --git a/src/frame/tests/site-tree.ts b/src/frame/tests/site-tree.ts
index a62099e603be..1be82f9da431 100644
--- a/src/frame/tests/site-tree.ts
+++ b/src/frame/tests/site-tree.ts
@@ -37,14 +37,12 @@ describe('siteTree', () => {
const ghesLatest = `enterprise-server@${latestEnterpriseRelease}`
const ghesSiteTree = siteTree.en[ghesLatest]
- // Find a page in the tree that we know contains Liquid
const pageWithDynamicTitle = findPageInSiteTree(
ghesSiteTree,
siteTree.en[nonEnterpriseDefaultVersion],
`/en/${ghesLatest}/admin/installing-your-enterprise-server`,
)
- // Confirm the raw title contains Liquid
expect(pageWithDynamicTitle.page.title).toEqual(
'Installing {% data variables.product.prodname_enterprise %}',
)
@@ -62,7 +60,7 @@ describe('siteTree', () => {
function validate(currentPage: Tree): void {
const childPages: Tree[] = currentPage.childPages || []
for (const childPage of childPages) {
- // Store page reference before validation to avoid type narrowing
+ // Store page reference before validation to avoid type narrowing.
const pageRef: Tree = childPage
const isValid = siteTreeValidate(childPage)
let errors: string | undefined
diff --git a/src/frame/tests/url-encoding.ts b/src/frame/tests/url-encoding.ts
index 2c4d0e8d32c9..6927f46ff21c 100644
--- a/src/frame/tests/url-encoding.ts
+++ b/src/frame/tests/url-encoding.ts
@@ -2,15 +2,12 @@ import { describe, expect, test } from 'vitest'
import { get } from '@/tests/helpers/e2etest'
describe('URL encoding for version paths', () => {
+ // SharePoint encodes @ as %40: /en/enterprise-cloud@latest becomes /en/enterprise-cloud%40latest.
test('handles URL-encoded @ symbol in enterprise-cloud version', async () => {
- // SharePoint encodes @ as %40, so /en/enterprise-cloud@latest becomes /en/enterprise-cloud%40latest
const encodedUrl = '/en/enterprise-cloud%40latest/copilot/concepts/chat'
const res = await get(encodedUrl)
- // Should either:
- // 1. Work directly (200) - the encoded URL should decode and work
- // 2. Redirect (301/302) to the proper decoded URL
- // Should NOT return 404
+ // Encoded @ may render directly or redirect to the decoded URL, but it must not 404.
expect([200, 301, 302]).toContain(res.statusCode)
if (res.statusCode === 301 || res.statusCode === 302) {
@@ -48,21 +45,20 @@ describe('URL encoding for version paths', () => {
})
test('URL encoding in other parts of URL is preserved', async () => {
- // Only @ symbols in version paths should be decoded, other encoding should be preserved
+ // A literal @ in the version segment must not decode unrelated URL encoding.
const encodedUrl = '/en/enterprise-cloud@latest/copilot/concepts/some%20page'
const res = await get(encodedUrl)
- // This might 404 if the page doesn't exist, but shouldn't break due to encoding
+ // Missing pages may 404, but unrelated URL encoding must not break the request.
expect(res.statusCode).not.toBe(500)
})
test('Express URL properties are correctly updated after decoding', async () => {
- // Test that req.path, req.query, etc. are properly updated when req.url is modified
+ // Updating req.url must also refresh Express request properties such as req.path and req.query.
const encodedUrl = '/en/enterprise-cloud%40latest/copilot/concepts/chat?test=value'
const res = await get(encodedUrl)
- // Should work correctly (200 or redirect) - the middleware should properly update
- // req.path from '/en/enterprise-cloud%40latest/...' to '/en/enterprise-cloud@latest/...'
+ // Middleware updates req.path from enterprise-cloud%40latest to enterprise-cloud@latest.
expect([200, 301, 302]).toContain(res.statusCode)
})
})
diff --git a/src/ghes-releases/lib/parse-release-notes.ts b/src/ghes-releases/lib/parse-release-notes.ts
index e235430cd314..b27fe866693f 100644
--- a/src/ghes-releases/lib/parse-release-notes.ts
+++ b/src/ghes-releases/lib/parse-release-notes.ts
@@ -1,7 +1,5 @@
-/**
- * Pure parsing/extraction functions used by generate-release-notes.ts.
- * Extracted here so they can be unit-tested without triggering the CLI.
- */
+// generate-release-notes.ts uses side-effect-free parsers.
+// Tests can import them without starting the CLI.
import fs from 'fs'
import { load } from 'js-yaml'
@@ -11,14 +9,11 @@ export interface NoteEntry {
sourceUrl: string
}
-/**
- * Looks for ```yaml ... ``` blocks, or falls back to lines starting with "- heading:"
- */
+// Agent output can omit fences, so fall back to the first line starting with "- heading:".
export function extractYaml(agentOutput: string): string | null {
const fenced = agentOutput.match(/```ya?ml\s*\n([\s\S]*?)```/)
if (fenced) return fenced[1].trim()
- // Fall back: look for lines that look like YAML note entries
const lines = agentOutput.split('\n')
const yamlLines: string[] = []
let inYaml = false
@@ -27,7 +22,7 @@ export function extractYaml(agentOutput: string): string | null {
inYaml = true
}
if (inYaml) {
- // Stop if we hit a non-YAML line (not indented, not a list item, not a comment, not empty)
+ // End fallback YAML when the response resumes prose.
if (line.trim() && !line.match(/^[\s#-]/) && !line.match(/^\s+\w+:/)) {
break
}
@@ -66,17 +61,12 @@ export function parseNoteEntries(yamlStr: string, sourceUrl: string): NoteEntry[
}
}
} catch {
- // Malformed YAML returns no entries rather than throwing.
+ // Bad agent YAML produces no entries so one issue cannot stop the run.
}
return entries
}
-/**
- * Parse an existing release notes YAML file and extract NoteEntry[] from it,
- * along with a set of source issue URLs already covered.
- * Returns { entries, coveredUrls } or null if the file doesn't exist.
- */
export function loadExistingEntries(yamlPath: string): {
entries: NoteEntry[]
coveredUrls: Set<string>
@@ -87,16 +77,8 @@ export function loadExistingEntries(yamlPath: string): {
return loadExistingEntriesFromString(content)
}
-/**
- * Parse release notes YAML content (as a string) and extract NoteEntry[] from it.
- * This is the testable core, with no file I/O.
- *
- * Note: This uses manual line-by-line parsing instead of js-yaml because we need
- * to preserve the `# https://github.com/.../issues/NNN` source URL comments that
- * precede each note. YAML comments are stripped by `load()` and aren't part
- * of the YAML data model, so a standard parser can't track the comment-to-note
- * relationship we rely on for incremental mode and deduplication.
- */
+// Parse release notes YAML manually so source issue URL comments stay attached to notes.
+// js-yaml strips comments, which would break incremental mode and deduplication.
export function loadExistingEntriesFromString(content: string): {
entries: NoteEntry[]
coveredUrls: Set<string>
@@ -150,7 +132,7 @@ export function loadExistingEntriesFromString(content: string): {
if (currentSection === 'changes') currentHeading = 'Changes'
else if (currentSection === 'closing_down') currentHeading = 'Closing down'
else if (currentSection === 'retired') currentHeading = 'Retired'
- else currentHeading = null // known_issues: skip
+ else currentHeading = null // Known issues stay in the placeholder template.
continue
}
@@ -213,10 +195,6 @@ export function loadExistingEntriesFromString(content: string): {
return { entries, coveredUrls }
}
-/**
- * Append YAML lines for a list of note entries at a given indentation level.
- * Handles the `# sourceUrl`, `- |`, and multi-line note content pattern.
- */
export function appendNoteLines(lines: string[], noteEntries: NoteEntry[], indent: string): void {
for (const entry of noteEntries) {
lines.push(`${indent}# ${entry.sourceUrl}`)
@@ -263,7 +241,6 @@ export function buildReleaseNotesYaml(
lines.push('sections:')
- // Features (grouped by heading).
const featureEntries = noteEntries.filter((e) => featureHeadings.includes(e.heading))
const otherEntries = noteEntries.filter((e) => !featureHeadings.includes(e.heading))
@@ -291,7 +268,6 @@ export function buildReleaseNotesYaml(
lines.push(' # TODO: Add feature notes')
}
- // Changes.
const changeEntries = otherEntries.filter((e) => !['Closing down', 'Retired'].includes(e.heading))
if (changeEntries.length > 0) {
lines.push('')
@@ -299,14 +275,12 @@ export function buildReleaseNotesYaml(
appendNoteLines(lines, changeEntries, ' ')
}
- // Known issues.
lines.push('')
lines.push(' known_issues:')
lines.push(' # TODO: Add known issues from "GHES Release Note Tracking" project')
lines.push(' - |')
lines.push(' ...')
- // Closing down.
const closingEntries = otherEntries.filter((e) => e.heading === 'Closing down')
if (closingEntries.length > 0) {
lines.push('')
@@ -314,7 +288,6 @@ export function buildReleaseNotesYaml(
appendNoteLines(lines, closingEntries, ' ')
}
- // Retired.
const retiredEntries = otherEntries.filter((e) => e.heading === 'Retired')
if (retiredEntries.length > 0) {
lines.push('')
diff --git a/src/ghes-releases/lib/release-issues.ts b/src/ghes-releases/lib/release-issues.ts
index 91e0d89cb3bd..f56c37f01956 100644
--- a/src/ghes-releases/lib/release-issues.ts
+++ b/src/ghes-releases/lib/release-issues.ts
@@ -7,9 +7,6 @@ interface IssueLike {
labels: { name: string }[]
}
-/**
- * Parse and validate the issue state filter. Defaults to "all".
- */
export function parseIssueState(value?: string): IssueState {
if (!value) return 'all'
@@ -41,9 +38,7 @@ export function buildReleaseIssueListArgs(version: string, issueState: IssueStat
]
}
-/**
- * Excludes release issues that should not produce GHES release notes.
- */
+// "public roadmap" and "not planned" issues never produce GHES release notes.
export function isExcludedReleaseIssue(issue: IssueLike): boolean {
return issue.labels.some((l) => EXCLUDED_RELEASE_LABELS.has(l.name.toLowerCase()))
}
diff --git a/src/ghes-releases/scripts/create-enterprise-issue.ts b/src/ghes-releases/scripts/create-enterprise-issue.ts
index b19db2e4366c..2d3ef022f680 100644
--- a/src/ghes-releases/scripts/create-enterprise-issue.ts
+++ b/src/ghes-releases/scripts/create-enterprise-issue.ts
@@ -1,7 +1,8 @@
-/**
- * @purpose Writer tool
- * @description Create release tracking issues for a new GHES version
- */
+// @purpose Writer tool
+// @description Create release tracking issues for a new GHES version
+//
+// Creates release and deprecation issues in github/docs-content and github/technical-content.
+// Skips a release or deprecation when its issue already exists.
import { readFileSync } from 'fs'
import { basename } from 'path'
import { Liquid } from 'liquidjs'
@@ -45,25 +46,15 @@ interface IssueSearchOpts {
titleMatch?: string
}
-// Required by github() to authenticate
if (!process.env.GITHUB_TOKEN) {
throw new Error('Error! You must have a GITHUB_TOKEN set in an .env file to run this script.')
}
const octokit = github()
const liquid = new Liquid()
-// [start-readme]
-//
-// This script creates enterprise release and deprecation issues in the
-// github/docs-content and github/technical-content repositories.
-// The script checks if an issue already exists for the release or deprecation.
-//
-// [end-readme]
run()
async function run() {
- // This script requires one parameters with the value
- // of either 'release' or 'deprecation'
const releaseType = process.argv[2]
if (releaseType !== 'release' && releaseType !== 'deprecation') {
throw new Error(
@@ -82,7 +73,6 @@ async function run() {
async function createDeprecationIssue() {
const repo = 'github/technical-content'
console.log('Next deprecation number: ', oldestSupported)
- // If an issue already exists for this release, do nothing
const issueExists = await isExistingIssue(repo, {
titleMatch: `Enterprise Server ${oldestSupported} deprecation steps`,
labels: ['enterprise deprecation'],
@@ -124,7 +114,6 @@ async function createReleaseIssue() {
const releaseNumber = getNextReleaseNumber(releaseDates)
console.log('Next release number: ', releaseNumber)
- // If an issue already exists for this release, do nothing
if (
await isExistingIssue(repo, {
labels: ['ghes-release-automation', `GHES ${releaseNumber}`],
@@ -136,8 +125,6 @@ async function createReleaseIssue() {
const releaseInfo = releaseDates[releaseNumber]
const rcDate = releaseInfo.release_candidate
- // Only open an issue if today is within 30 days before
- // the release candidate date
if (getNumberDaysUntilMilestone(rcDate || '') > 30) {
console.log(
`The ${releaseNumber} release candidate is not until ${rcDate}! An issue will be opened 30 days prior to the release candidate date.`,
@@ -147,8 +134,7 @@ async function createReleaseIssue() {
const releaseTemplates = getReleaseTemplates()
- // Set shell issues with placeholder title and body
- // Need all issue numbers before filling in liquid templates
+ // Create placeholder issues first because Liquid templates need every issue URL.
for (const templateName of Object.keys(releaseTemplates)) {
const issue = await createIssue(
repo,
@@ -161,7 +147,6 @@ async function createReleaseIssue() {
releaseTemplates[templateName].issue = issue.data
}
- // Go back and update title and body with rendered liquid templates
const releaseTemplateContext = getReleaseTemplateContext(
releaseNumber,
releaseInfo,
@@ -201,7 +186,6 @@ async function createIssue(
throw error
}
if (issue.status === 201) {
- // Write the values to disk for use in the workflow.
console.log(
`Issue #${issue.data.number} for the ${releaseNumber} ${releaseType} was opened: ${issue.data.html_url}`,
)
@@ -305,15 +289,12 @@ function getReleaseTemplateContext(
'release-code-freeze-date': releaseInfo.code_freeze || '',
'release-rc-target-date': releaseInfo.release_candidate || '',
}
- // Add a context variable for each issue url
for (const [templateName, template] of Object.entries(releaseTemplates)) {
if (template.issue) {
context[`${templateName}-url`] = template.issue.html_url
}
}
- // Create a context variable for each of the
- // 7 days before release-rc-target-date
if (releaseInfo.release_candidate) {
const rcTargetDate = new Date(releaseInfo.release_candidate).getTime()
for (let i = 1; i <= 7; i++) {
@@ -356,10 +337,6 @@ function getNextReleaseNumber(releaseDates: ReleaseDates): string {
return Object.keys(releaseDates)[indexOfNext]
}
-// examples:
-// searchQuery: 'author:docs-bot is:open'
-// labels: ['enterprise deprecation', 'ghes 3.0']
-// titleMatch: 'GHES 3.0'
async function isExistingIssue(
repo: string,
opts: IssueSearchOpts = { labels: undefined, searchQuery: undefined, titleMatch: undefined },
diff --git a/src/ghes-releases/scripts/deprecate/archive-version.ts b/src/ghes-releases/scripts/deprecate/archive-version.ts
index 9c1f807ba498..46b0a8183f18 100755
--- a/src/ghes-releases/scripts/deprecate/archive-version.ts
+++ b/src/ghes-releases/scripts/deprecate/archive-version.ts
@@ -1,10 +1,5 @@
-// [start-readme]
-//
-// Run this script during the Enterprise deprecation process to download
-// static copies of all pages for the oldest supported Enterprise version.
-// See the Enterprise deprecation issue template for instructions.
-//
-// [end-readme]
+// Run during Enterprise deprecation to download static pages for the oldest supported version.
+// The Enterprise deprecation issue template owns the operational checklist.
import path from 'path'
import fs from 'fs'
@@ -90,7 +85,6 @@ async function main() {
}
}
- // remove temp directory
await fs.promises.rm(tmpArchivalDirectory, { recursive: true, force: true })
const app = createApp()
@@ -103,8 +97,7 @@ async function main() {
await scrape({
urls,
urlFilter: (url: string) => {
- // Do not download assets from other hosts like S3 or octodex.github.com
- // (this will keep them as remote references in the downloaded pages)
+ // Leave assets on other hosts as remote references in downloaded pages.
return url.startsWith(`http://localhost:${port}/`)
},
directory: tmpArchivalDirectory,
@@ -126,7 +119,7 @@ async function main() {
console.log(`\n\ndone scraping! added files to ${tmpArchivalDirectory}\n`)
if (!singlePage) {
- // create redirect html files to preserve frontmatter redirects
+ // Redirect files preserve frontmatter redirects after static scraping.
await createRedirectsFile(pageList, path.join(tmpArchivalDirectory, version))
console.log(`next step: deprecate ${version} in lib/enterprise-server-releases.ts`)
} else {
@@ -148,9 +141,9 @@ async function createRedirectsFile(pageList: PageList, outputDirectory: string)
const redirectEntries: Array<[string, string]> = Object.entries(redirects)
for (let [oldPath, newPath] of redirectEntries) {
- // remove any liquid variables that sneak in
+ // Redirect paths can include Liquid version variables.
oldPath = oldPath.replace('/{{ page.version }}', '').replace('/{{ currentVersion }}', '')
- // ignore any old paths that are not in this version
+ // Keep only redirects for the archived Enterprise version.
if (
!(
oldPath.includes(`/enterprise-server@${version}`) ||
diff --git a/src/ghes-releases/scripts/deprecate/collapse-blank-lines.ts b/src/ghes-releases/scripts/deprecate/collapse-blank-lines.ts
index 52815b0b91d8..29290bf4a2b4 100644
--- a/src/ghes-releases/scripts/deprecate/collapse-blank-lines.ts
+++ b/src/ghes-releases/scripts/deprecate/collapse-blank-lines.ts
@@ -1,13 +1,9 @@
import fs from 'fs'
import { execSync } from 'child_process'
-// Removing deprecated Liquid conditionals leaves behind extra blank lines.
-// The content team flags these every deprecation, and the MD012 linter rule
-// is off so nothing catches them automatically. This collapses any run of
-// two or more consecutive blank lines down to one, but only in the markdown
-// files the deprecation actually changed. Single blank lines are left alone:
-// removed Liquid can introduce one in a place where it doesn't belong, so a
-// human still reviews each removal site one at a time.
+// Deprecated Liquid conditionals leave extra blank lines that content reviewers flag.
+// MD012 does not catch them in this repo. Collapse runs of two or more blank lines only in
+// markdown files changed by deprecation. Single blank lines still need human review.
function getChangedMarkdownFiles(): string[] {
const commands = [
@@ -21,7 +17,7 @@ function getChangedMarkdownFiles(): string[] {
try {
output = execSync(command, { encoding: 'utf8' })
} catch {
- // origin/main may not be fetched locally; skip that source.
+ // Skip origin/main when it is not fetched locally.
continue
}
for (const line of output.split('\n')) {
@@ -35,7 +31,6 @@ function getChangedMarkdownFiles(): string[] {
return [...files].sort()
}
-// Collapses any run of 2+ blank lines into a single blank line.
function collapse(contents: string): string {
const lines = contents.split('\n')
const result: string[] = []
diff --git a/src/ghes-releases/scripts/deprecate/create-docs-ghes-version-repo.sh b/src/ghes-releases/scripts/deprecate/create-docs-ghes-version-repo.sh
index 76f7be8ef6d9..b357b9add60e 100755
--- a/src/ghes-releases/scripts/deprecate/create-docs-ghes-version-repo.sh
+++ b/src/ghes-releases/scripts/deprecate/create-docs-ghes-version-repo.sh
@@ -1,13 +1,11 @@
-# This script creates a new repository for an archived version of GitHub Enterprise Server documentation.
-# Please update the version variable first.
-# You may wish to run this script a little bit at a time instead of all at once incase there are any errors.
+# Creates a repository for an archived GitHub Enterprise Server documentation version.
+# Pass the version as the first argument, and run sections one at a time when inspecting failures.
version=$1
cd ~/Documents/gh/github
-# Teams are addressed by numeric ID because IDs survive team renames and slugs do not.
-# Some APIs (repo creation, CODEOWNERS, custom properties) only accept slugs, so
-# resolve the current slug from the ID at runtime rather than hardcoding it.
+# Numeric team IDs survive team renames; slugs do not.
+# Repo creation, CODEOWNERS, and custom properties require slugs, so resolve current slugs.
org_id=9919
docs_team_id=325922
docs_eng_team_id=3935808
diff --git a/src/ghes-releases/scripts/deprecate/rewrite-asset-paths.ts b/src/ghes-releases/scripts/deprecate/rewrite-asset-paths.ts
index 0ae4cc3cd8ad..a04414779db9 100644
--- a/src/ghes-releases/scripts/deprecate/rewrite-asset-paths.ts
+++ b/src/ghes-releases/scripts/deprecate/rewrite-asset-paths.ts
@@ -24,6 +24,7 @@ export class RewriteAssetPathsPlugin {
this.replaceUrl = replaceUrl
}
+ // HTML and CSS asset paths must point at the archive site unless local-dev leaves them relative.
apply(
registerAction: (event: string, callback: (args: ResourceSavedArgs) => Promise<void>) => void,
) {
@@ -35,12 +36,8 @@ export class RewriteAssetPathsPlugin {
const text = resource.getText()
let newBody = text
- // Rewrite HTML asset paths. Example:
- // ../assets/images/foo/bar.png ->
- // https://github.github.com/docs-ghes-3.10/assets/images/foo/bar.png
-
if (resource.isHtml()) {
- // Remove nextjs scripts and manifest.json link
+ // Next.js runtime files break static archives.
newBody = newBody.replace(
/<script\ssrc="(\.\.\/)*_next\/static\/[\w]+\/(_buildManifest|_ssgManifest).js?".*?><\/script>/g,
'',
@@ -58,11 +55,6 @@ export class RewriteAssetPathsPlugin {
}
}
- // Rewrite CSS asset paths. Example
- // url("../assets/fonts/alliance/alliance-no-1-regular.woff") ->
- // url("https://github.github.com/docs-ghes-3.10/assets/fonts/alliance/alliance-no-1-regular.woff")
- // url(../../../assets/cb-303/images/octicons/search-24.svg) ->
- // url(https://github.github.com/docs-ghes-3.10/assets/cb-303/images/octicons/search-24.svg)
if (resource.isCss()) {
if (!this.localDev) {
newBody = newBody.replace(
diff --git a/src/ghes-releases/scripts/deprecate/update-automated-pipelines.ts b/src/ghes-releases/scripts/deprecate/update-automated-pipelines.ts
index 46c1f1a0ae04..c237d016948c 100755
--- a/src/ghes-releases/scripts/deprecate/update-automated-pipelines.ts
+++ b/src/ghes-releases/scripts/deprecate/update-automated-pipelines.ts
@@ -1,13 +1,6 @@
-// [start-readme]
-//
-// This script adds and removes placeholder data files in the
-// automation pipelines data directories and
-// data/release-notes/enterprise-server directories. This script
-// uses the supported and deprecated versions to determine what
-// directories should exist. This script also modifies the `api-versions`
-// key if it exists in a pipeline's lib/config.json file.
-//
-// [end-readme]
+// Adds and removes placeholder data for automation pipelines and GHES release notes
+// from the supported and deprecated GHES versions.
+// Updates api-versions in each pipeline lib/config.json when that key exists.
import { existsSync, rmSync } from 'fs'
import { mkdir, readFile, readdir, writeFile, cp } from 'fs/promises'
@@ -20,8 +13,8 @@ const pipelines = JSON.parse(await readFile('src/automated-pipelines/lib/config.
'automation-pipelines'
]
-// If the config file for a pipeline includes `api-versions` update that list
-// based on the supported and deprecated releases.
+// Pipelines with api-versions copy previous calendar date variants to the current release.
+// Deprecated variants are dropped.
export async function updateAutomatedConfigFiles() {
for (const pipeline of pipelines) {
const configFilepath = `src/${pipeline}/lib/config.json`
@@ -29,12 +22,10 @@ export async function updateAutomatedConfigFiles() {
const apiVersions = configData['api-versions']
if (!apiVersions) continue
for (const key of Object.keys(apiVersions)) {
- // Copy the previous release's calendar date versions to the new release
if (key.endsWith(previousReleaseNumber)) {
const newKey = key.replace(previousReleaseNumber, currentReleaseNumber)
apiVersions[newKey] = apiVersions[key]
}
- // Remove any deprecated versions
for (const deprecatedRelease of deprecated) {
if (key.endsWith(deprecatedRelease)) {
delete apiVersions[key]
@@ -49,15 +40,9 @@ export async function updateAutomatedConfigFiles() {
}
export async function updateAutomatedPipelines() {
- // The allVersions object uses the 'api-versions' data stored in the
- // src/rest/lib/config.json file. We want to update 'api-versions'
- // before the allVersions object is created so we need to import it
- // after calling updateAutomatedConfigFiles.
+ // Import allVersions after config updates so src/rest/lib/config.json changes take effect.
const { allVersions } = await import('@/versions/lib/all-versions')
- // Gets all of the base names (e.g., ghes-) in the allVersions object
- // Currently, this is only ghes- but if we had more than one type of
- // numbered release it would get all of them.
const numberedReleaseBaseNames = Array.from(
new Set(
Object.values(allVersions)
@@ -66,12 +51,7 @@ export async function updateAutomatedPipelines() {
),
)
- // A list of currently supported versions (calendar date inclusive)
- // in the format using the short name rather than full format
- // (e.g., enterprise-server@). The list is filtered
- // to only include versions that have numbered releases (e.g. ghes-).
- // The list is generated from the `apiVersions` key in allVersions.
- // This is currently only needed for the rest and github-apps pipelines.
+ // rest and github-apps read calendar-date versions from allVersions.apiVersions.
const versionNamesCalDate = Object.values(allVersions)
.filter((version) => version.hasNumberedReleases)
.map((version) =>
@@ -80,16 +60,13 @@ export async function updateAutomatedPipelines() {
: version.openApiVersionName,
)
.flat()
- // A list of currently supported versions in the format using the short name
- // rather than the full format (e.g., enterprise-server@). The list is filtered
- // to only include versions that have numbered releases (e.g. ghes-).
- // Currently, this is used for the graphql and webhooks pipelines.
+ // graphql and webhooks read numbered versions in ghes-major.minor form.
const versionNames = Object.values(allVersions)
.filter((version) => version.hasNumberedReleases)
.map((version) => version.openApiVersionName)
for (const pipeline of pipelines) {
- // secret-scanning has a different directory structure than the others
+ // secret-scanning stores pattern docs outside the shared pipeline data layout.
const directoryWithReleases =
pipeline === 'secret-scanning'
? 'src/secret-scanning/data/pattern-docs'
@@ -101,8 +78,7 @@ export async function updateAutomatedPipelines() {
)['api-versions']
const directoryListing = await readdir(directoryWithReleases)
- // filter the directory list to only include directories that start with
- // basenames with numbered releases (e.g., ghes-).
+ // Limit pipeline data dirs to numbered release basenames like ghes-.
const existingDataDir = directoryListing.filter((directory) =>
numberedReleaseBaseNames.some((basename) => directory.startsWith(basename)),
)
@@ -113,19 +89,15 @@ export async function updateAutomatedPipelines() {
const expectedDirectory = isCalendarDateVersioned ? versionNamesCalDate : versionNames
- // Get a list of data directories to remove (deprecate) and remove them
- // This should only happen if a release is being deprecated.
const removeFiles = difference(existingDataDir, expectedDirectory)
for (const directory of removeFiles) {
console.log(`Removing src/${pipeline}/data/${directory}`)
rmSync(`src/${pipeline}/data/${directory}`, { recursive: true, force: true })
}
- // Get a list of data directories to create (release) and create them
- // This should only happen if a release is being added.
const addFiles = difference(expectedDirectory, existingDataDir)
- // Verify all new directories belong to the current release
+ // Reject directories unrelated to the current release before creating them.
for (const dir of addFiles) {
if (!dir.includes(currentReleaseNumber)) {
throw new Error(
@@ -136,15 +108,10 @@ export async function updateAutomatedPipelines() {
}
for (const base of numberedReleaseBaseNames) {
- // Find ALL directories to add for this base name (may be multiple
- // when a release has more than one calendar-date version).
+ // Calendar-date releases can add more than one directory for the same base name.
const dirsToAdd = addFiles.filter((item) => item.startsWith(base))
for (const dirToAdd of dirsToAdd) {
- // Derive the previous release's corresponding directory by replacing
- // the current release number with the previous one. This correctly
- // maps each calendar-date variant to its predecessor, e.g.:
- // ghes-3.20-2022-11-28 -> ghes-3.19-2022-11-28
- // ghes-3.20-2026-03-10 -> ghes-3.19-2026-03-10
+ // Keep calendar-date suffixes unchanged when mapping previous dirs to current dirs.
const previousDirName = dirToAdd.replace(currentReleaseNumber, previousReleaseNumber)
if (!existingDataDir.includes(previousDirName)) {
throw new Error(
@@ -163,9 +130,7 @@ export async function updateAutomatedPipelines() {
}
}
- // Add and remove the GHES release note data. Once we create an automation
- // pipeline for release notes, we can remove this because it will use the
- // same directory structure as the other pipeline data directories.
+ // GHES release notes stay in this path until an automation pipeline owns the same layout.
const ghesReleaseNotesDirs = await readdir('data/release-notes/enterprise-server')
const supportedHyphenated = supported.map((version) => version.replace('.', '-'))
const deprecatedHyphenated = deprecated.map((version) => version.replace('.', '-'))
diff --git a/src/ghes-releases/scripts/deprecate/update-content.ts b/src/ghes-releases/scripts/deprecate/update-content.ts
index 07422ed63dde..35004217f1a7 100644
--- a/src/ghes-releases/scripts/deprecate/update-content.ts
+++ b/src/ghes-releases/scripts/deprecate/update-content.ts
@@ -17,9 +17,8 @@ const contentFiles = walkFiles('content', {
ignore: ['**/README.md', '**/index.md'],
})
-// This module updates the versions frontmatter in content files.
-// When a content file contains only deprecated GHES releases, the
-// file is deleted and removed from the parent index.md file.
+// Updates versions frontmatter during GHES deprecation.
+// Deletes GHES-only files with no supported release from their parent index.md.
export function updateContentFiles() {
for (const file of contentFiles) {
const oldContents = fs.readFileSync(file, 'utf8')
@@ -35,16 +34,13 @@ export function updateContentFiles() {
throw new Error(`Could not load feature versions from ${featureFilePath}`)
}
- // skip files with no Enterprise Server versions frontmatter
if (!data.versions.ghes && !featureData?.versions?.ghes) continue
- // skip files with all ghes releases defined
if (data.versions.ghes === '*') continue
const deprecatedRelease = deprecated[0]
const oldestRelease = supported[supported.length - 1]
- // If the frontmatter versions.ghes property is now
- // applicable to all GHES releases, update the value to '*'.
+ // Feature-backed content becomes all versions when it applies to FPT, GHEC, and every GHES.
const featureAppliesToAllVersions =
featureData &&
featureData.versions.ghec &&
@@ -55,9 +51,7 @@ export function updateContentFiles() {
if (isInAllGhes(data.versions.ghes)) {
console.log('Updating GHES version in: ', file)
data.versions.ghes = '*'
- // To preserve newlines when stringifying,
- // you can set the lineWidth option to -1
- // This prevents updates to the file that aren't actual changes.
+ // lineWidth -1 preserves existing newlines, so only frontmatter changes are written.
fs.writeFileSync(
file,
frontmatter.stringify(content!, data, { lineWidth: -1 } as unknown as Parameters<
@@ -73,9 +67,7 @@ export function updateContentFiles() {
ghec: '*',
ghes: '*',
}
- // To preserve newlines when stringifying,
- // you can set the lineWidth option to -1
- // This prevents updates to the file that aren't actual changes.
+ // lineWidth -1 preserves existing newlines, so only frontmatter changes are written.
fs.writeFileSync(
file,
frontmatter.stringify(content!, data, { lineWidth: -1 } as unknown as Parameters<
@@ -87,9 +79,7 @@ export function updateContentFiles() {
const deprecatedRegex = new RegExp(`(<|<=)\\s?${deprecatedRelease}`, 'g')
const oldestRegex = new RegExp(`<\\s?${oldestRelease}`, 'g')
- // If the frontmatter versions.ghes property is now
- // deprecated, remove it. If the content file is only
- // versioned for GHES, remove the file and update index.md.
+ // Remove GHES frontmatter or delete GHES-only files when no supported GHES applies.
const featureGhes = featureData?.versions?.ghes || ''
const appliesToNoSupportedGhesReleases =
deprecatedRegex.test(data.versions.ghes) ||
@@ -101,7 +91,6 @@ export function updateContentFiles() {
if (Object.keys(data.versions).length === 1) {
removeFileUpdateParent(file)
} else {
- // Remove the ghes property from versions Fm and return
delete data.versions.ghes
console.log('Removing GHES version from: ', file)
fs.writeFileSync(
@@ -130,15 +119,14 @@ function removeFileUpdateParent(filePath: string) {
data: { children: string[] } | undefined
}
if (!data) return
- // Children paths are relative to the index.md file's directory
+ // Children paths are relative to the index.md file's directory.
const childPath = filePath.endsWith('index.md')
? `/${path.basename(path.dirname(filePath))}`
: `/${path.basename(filePath, '.md')}`
- // Remove the childPath from the parent index.md file's children frontmatter
data.children = data.children.filter((child) => child !== childPath)
- // If removing the childPath leaves the parent index.md file empty, remove it
+ // Empty parent indexes must disappear with their last child.
if (data.children.length === 0) {
removeFileUpdateParent(parentFilePath)
} else {
@@ -152,15 +140,10 @@ function removeFileUpdateParent(filePath: string) {
}
}
-// Gets the next parent file path.
-// If the filePath is an article (e.g., doesn't end with index.md),
-// then the parent file is the index.md file in the same directory.
-// If the filePath is a category or subcategory (e.g., ends with index.md),
-// the parent is the index.md file in the next directory up.
+// Articles use the index.md in their directory; index.md files use the parent directory's index.md.
+// content/index.md has no parent.
function getParentFilePath(filePath: string) {
- // This is the root index.md file, it has no parent
if (!filePath || filePath === 'content/index.md') return null
- // Handle index.md files with index.md parent in directory above
if (filePath.endsWith('index.md')) {
const pathParts = filePath.split('/')
pathParts.pop()
@@ -168,6 +151,5 @@ function getParentFilePath(filePath: string) {
pathParts.push('index.md')
return pathParts.join('/')
}
- // Handle articles with a parent index.md file
return filePath.replace(path.basename(filePath), 'index.md')
}
diff --git a/src/ghes-releases/scripts/deprecate/update-data.ts b/src/ghes-releases/scripts/deprecate/update-data.ts
index 08e91ce9e9b1..9b9badeff590 100644
--- a/src/ghes-releases/scripts/deprecate/update-data.ts
+++ b/src/ghes-releases/scripts/deprecate/update-data.ts
@@ -31,8 +31,7 @@ export function updateDataFiles() {
updateFeatureData()
}
-// Removes empty data/reusables files and removes the deleted
-// reusable from any content or data/reusables files that reference it.
+// Remove empty reusable files and their Liquid references so content does not use deleted data.
function updateReusableData() {
const deletedDataFiles = []
@@ -44,16 +43,12 @@ function updateReusableData() {
deletedDataFiles.push(file)
}
}
- // Map the format:
- // data/reusables/actions/actions-runner-controller-unsupported-customization.md
- // to the format:
- // {% data reusables.code-scanning.beta-org-enable-all %}
+ // Example: data/reusables/actions/runner.md becomes {% data reusables.actions.runner %}.
const reusableNames = deletedDataFiles.map(
(file) => `{% data ${file.replace('.md', '').split('/').slice(1).join('.')} %}`,
)
const existingDataReusables = difference(dataReusables, deletedDataFiles)
- // Remove deleted reusables from content and data resuables files
for (const file of [...existingDataReusables, ...contentFiles]) {
const originalContent = fs.readFileSync(file, 'utf8')
let content = originalContent
@@ -70,9 +65,7 @@ function updateReusableData() {
}
}
-// Removes deprecated data/feature files and outputs a list of data/features
-// available in all versions. That list is only used for review during a GHES
-// deprecation.
+// Lists all-version data/features for human review during GHES deprecation.
function updateFeatureData() {
const allFeatureFiles = new Set()
diff --git a/src/ghes-releases/scripts/generate-release-notes.ts b/src/ghes-releases/scripts/generate-release-notes.ts
index 1ecdd3ab3b21..9da6ed83aada 100644
--- a/src/ghes-releases/scripts/generate-release-notes.ts
+++ b/src/ghes-releases/scripts/generate-release-notes.ts
@@ -1,13 +1,8 @@
-/**
- * @purpose Writer tool
- * @description Generate GHES release notes from github/releases issues using Copilot CLI
- *
- * Generate GHES release notes by:
- * 1. Querying github/releases issues labeled "GHES <version>" (all states by default)
- * 2. Finding corresponding changelog PRs in github/blog
- * 3. Running each through the ghes-release-notes agent via Copilot CLI
- * 4. Stitching the YAML outputs into a release notes file
- */
+// @purpose Writer tool
+// @description Generate GHES release notes from github/releases issues using Copilot CLI
+//
+// Queries github/releases issues labeled with the GHES release number, all states by default.
+// Matches github/blog changelog PRs, runs ghes-release-notes, and writes release note YAML.
import { Command } from 'commander'
import { execFileSync, spawn, type ChildProcess } from 'child_process'
import fs from 'fs'
@@ -80,9 +75,7 @@ function loadFeatureHeadings(): string[] {
return _featureHeadingsCache
}
-/**
- * Run `gh` CLI commands with native auth (no GITHUB_TOKEN interference)
- */
+// Drop GITHUB_TOKEN so gh uses native auth instead of repo workflow auth.
function gh(args: string[]): string {
const env = { ...process.env }
delete env.GITHUB_TOKEN
@@ -105,11 +98,8 @@ interface ChangelogInfo {
body: string | null
}
-/**
- * Try to extract a changelog PR URL from a release issue body.
- * Looks for patterns like:
- * 📄 **Changelog post:** https://github.com/github/blog/pull/1234
- */
+// Release issues can link the changelog PR in a Changelog post field.
+// Example field: Changelog post. The value is a github/blog pull request URL.
function extractChangelogPrUrl(issueBody: string): string | null {
const match = issueBody.match(/https:\/\/github\.com\/github\/blog\/pull\/\d+/)
return match ? match[0] : null
@@ -125,11 +115,8 @@ function fetchChangelogPrBody(prUrl: string): string | null {
}
}
-/**
- * Search github/blog for a merged PR that references a release issue number.
- * Caches the fetched PR list to avoid redundant API calls.
- * Returns URL + body when found.
- */
+// Cache recent github/blog changelog PRs because multiple release issues search the same list.
+// Each changelog PR body links back to its release issue.
let _blogPrsCache: { number: number; body: string; url: string }[] | null = null
function searchChangelogPr(issueNumber: number): ChangelogInfo | null {
try {
@@ -170,10 +157,6 @@ function searchChangelogPr(issueNumber: number): ChangelogInfo | null {
return null
}
-/**
- * Find the changelog PR for a release issue, checking the issue body first,
- * then falling back to searching github/blog. Returns URL + body.
- */
function findChangelogPr(issue: ReleaseIssue): ChangelogInfo | null {
const fromBody = extractChangelogPrUrl(issue.body)
if (fromBody) {
@@ -183,11 +166,8 @@ function findChangelogPr(issue: ReleaseIssue): ChangelogInfo | null {
return searchChangelogPr(issue.number)
}
-/**
- * Resolve the Copilot CLI path.
- * Result is cached after first call.
- */
let _copilotCliPath: string | null = null
+// The VS Code extension fallback covers macOS only; otherwise which must find a global install.
function findCopilotCli(): string {
if (_copilotCliPath) return _copilotCliPath
@@ -199,10 +179,6 @@ function findCopilotCli(): string {
}
} catch {}
- // Fallback: check VS Code extension storage locations.
- // These paths are macOS-only. On Linux/Windows the `which` check above should
- // find Copilot CLI if it's installed globally. If needed, add platform-specific
- // paths here (e.g., ~/.config/Code/User/globalStorage/... for Linux).
const homeDir = os.homedir()
const vsCodePath = path.join(
homeDir,
@@ -225,11 +201,6 @@ function findCopilotCli(): string {
throw new Error('Copilot CLI not found. Install via: npm install -g @github/copilot@prerelease')
}
-/**
- * Run the ghes-release-notes agent on a release issue (+optional changelog PR)
- * via Copilot CLI and return the raw output.
- * Uses async spawn so SIGINT (Ctrl+C) is not blocked.
- */
interface AgentContext {
issueUrl: string
issueTitle: string
@@ -239,32 +210,27 @@ interface AgentContext {
featureHeadings: string[]
}
-/**
- * Extract the title tag (e.g., "GA", "Public Preview") from a release issue title.
- */
function parseTitleTag(title: string): string | null {
const match = title.match(/\[(GA|Public Preview|Beta|Private Preview|Closing Down|Retired)\]/i)
return match ? match[1] : null
}
+// Use async spawn so Ctrl+C can interrupt the agent process.
function runAgent(ctx: AgentContext): Promise<string> {
const copilotPath = findCopilotCli()
const titleTag = parseTitleTag(ctx.issueTitle)
- // Build an optimized prompt that pre-includes all context so the agent
- // doesn't need to make tool calls to fetch it.
+ // Preload context so the agent does not need network tools during note generation.
let prompt = `You are running in non-interactive mode. Do NOT ask any follow-up questions. `
prompt += `Generate a release note for ${ctx.issueUrl}. `
prompt += `Follow the ghes-release-notes agent instructions. `
prompt += `Return ONLY a single YAML code block (\`\`\`yaml ... \`\`\`). No conversation, no questions, no explanations outside the code block.\n\n`
- // Pre-supply the title tag so the agent doesn't need to re-parse
if (titleTag) {
prompt += `The issue title tag is [${titleTag}].\n\n`
}
- // Pre-supply valid headings so the agent doesn't need to read PLACEHOLDER-TEMPLATE.yml
prompt += `IMPORTANT: Do NOT read PLACEHOLDER-TEMPLATE.yml or data/variables/product.yml — all necessary context is provided below.\n\n`
prompt += `Valid feature headings (use ONLY these for feature notes):\n`
for (const h of ctx.featureHeadings) {
@@ -272,13 +238,11 @@ function runAgent(ctx: AgentContext): Promise<string> {
}
prompt += `\nFor non-feature notes, use: Changes, Closing down, or Retired.\n\n`
- // Pre-supply the issue body so the agent doesn't need to fetch it
prompt += `--- RELEASE ISSUE (${ctx.issueUrl}) ---\n`
prompt += `Title: ${ctx.issueTitle}\n`
prompt += ctx.issueBody.substring(0, 15000)
prompt += `\n--- END RELEASE ISSUE ---\n\n`
- // Pre-supply the changelog PR body if available
if (ctx.changelogUrl && ctx.changelogBody) {
prompt += `--- CHANGELOG PR (${ctx.changelogUrl}) ---\n`
prompt += ctx.changelogBody.substring(0, 10000)
@@ -379,14 +343,8 @@ interface AgentResult {
skipWarning?: string
}
-/**
- * Run the agent with retry logic. Retries up to `maxRetries` times on failure.
- * Validates that extracted YAML parses into non-empty entries before accepting.
- * If the agent tries to skip (returns `# SKIP: reason` + `[]`), treats it as a
- * failed attempt and retries, because issues that matched the GHES label filter should
- * always get a release note. If all attempts result in skips, the last skip
- * reason is attached as a warning.
- */
+// Retry agent failures and reject empty YAML so matching GHES issues produce release notes.
+// Skip signals become warnings only after every attempt skips.
async function runAgentWithRetry(ctx: AgentContext, maxRetries = 2): Promise<AgentResult> {
let lastError: Error | null = null
let lastRawOutput = ''
@@ -397,8 +355,7 @@ async function runAgentWithRetry(ctx: AgentContext, maxRetries = 2): Promise<Age
lastRawOutput = output
const yamlStr = extractYaml(output)
if (yamlStr) {
- // Detect agent skip signals and treat as retryable failures.
- // The issue already matched GHES labels, so we always want a release note.
+ // Treat skip signals as retryable because GHES-labeled issues need notes.
const skipReason =
extractSkipReason(yamlStr) ||
(Array.isArray(load(yamlStr)) && (load(yamlStr) as unknown[]).length === 0
@@ -418,7 +375,7 @@ async function runAgentWithRetry(ctx: AgentContext, maxRetries = 2): Promise<Age
skipWarning: lastSkipReason ?? undefined,
}
}
- // YAML was extracted but is empty or unparseable, so retry.
+ // Retry empty or unparseable YAML.
lastError = new Error(
`Agent returned YAML but it contained no valid entries (got: ${yamlStr.substring(0, 80)})`,
)
@@ -447,7 +404,7 @@ program
)
.requiredOption('-r, --release <version>', 'GHES release number (e.g., 3.20, 3.21)')
.option('--rc [boolean]', 'Generate release candidate notes (omit for GA)', (val: string) => {
- // Support both `--rc` (no value → true) and `--rc true`/`--rc false` (legacy)
+ // Accept --rc alone, --rc true, and --rc false.
if (val === undefined || val === 'true') return true
if (val === 'false') return false
return true
@@ -462,7 +419,7 @@ program
'-i, --issue <value>',
'Process a single issue by number or URL (replaces its entry if it already exists)',
(val: string) => {
- // Accept a full URL like https://github.com/github/releases/issues/6768
+ // Accept full github/releases issue URLs as well as numbers.
const urlMatch = val.match(/\/issues\/(\d+)/)
if (urlMatch) return parseInt(urlMatch[1], 10)
const num = parseInt(val, 10)
@@ -496,7 +453,6 @@ program
process.exit(1)
}
- // Prerequisite checks.
try {
execFileSync('gh', ['--version'], { stdio: 'ignore' })
} catch {
@@ -524,7 +480,6 @@ program
process.exit(1)
}
- // Step 1: Fetch release issues.
let issues: ReleaseIssue[]
if (singleIssue) {
@@ -570,12 +525,11 @@ program
process.exit(0)
}
- // GA meta-issues (e.g. "GHES 3.20 GA [GA]") are tracking issues, not features.
+ // GA meta-issues named GHES X.Y GA or GHES X.Y release are tracking issues.
const originalCount = issues.length
issues = issues.filter((issue) => {
const title = issue.title.trim()
const stripped = title.replace(/\s*\[[^\]]*\]/g, '').trim()
- // Skip issues whose title is just "GHES X.Y GA" or "GHES X.Y release"
if (/^ghes\s+\d+\.\d+\s+ga$/i.test(stripped)) return false
if (/^ghes\s+\d+\.\d+\s+release$/i.test(stripped)) return false
return true
@@ -613,14 +567,14 @@ program
const outputDir = path.join(process.cwd(), 'data/release-notes/enterprise-server', dirName)
const outputPath = path.join(outputDir, fileName)
- // Incremental mode: load existing entries.
+ // Existing entries make generation incremental by default.
const allEntries: NoteEntry[] = []
let existingCoveredUrls = new Set<string>()
if (!force && !stdout && fs.existsSync(outputPath)) {
const existing = loadExistingEntries(outputPath)
if (existing && existing.entries.length > 0) {
- // When --issue is specified, remove the old entry for that issue so it gets regenerated
+ // Regenerate a single issue by dropping its previous source URL entry first.
if (singleIssue) {
const issueUrl = `https://github.com/github/releases/issues/${singleIssue}`
const kept = existing.entries.filter((e) => e.sourceUrl !== issueUrl)
@@ -638,7 +592,7 @@ program
}
}
- // Filter out issues already covered by existing file (incremental mode)
+ // Incremental mode skips release issues already covered by the existing file.
if (existingCoveredUrls.size > 0 && !singleIssue) {
const beforeCount = issues.length
issues = issues.filter((issue) => !existingCoveredUrls.has(issue.url))
@@ -652,7 +606,6 @@ program
}
}
- // Step 2: Find changelog PRs.
spinner.start('Finding changelog PRs...')
const issueChangelogMap = new Map<number, ChangelogInfo | null>()
let changelogFound = 0
@@ -664,14 +617,12 @@ program
}
spinner.succeed(`Found changelog PRs for ${changelogFound}/${issues.length} issues`)
- // Step 3: Run agent on each issue.
const failures: { issue: ReleaseIssue; error: string }[] = []
const existingEntryCount = allEntries.length
- // Hoisted for clarity. The underlying load is already cached.
const featureHeadings = loadFeatureHeadings()
- // Helper to write current entries to file (called after each success and on Ctrl+C)
+ // Flush after each success and on Ctrl+C so long runs keep completed notes.
const writeCurrentOutput = () => {
if (stdout || allEntries.length === 0) return
try {
@@ -712,15 +663,14 @@ program
)
}
- // entries are pre-validated by runAgentWithRetry, but re-parse for the actual list
+ // Re-parse validated YAML so the main list uses parseNoteEntries output.
const entries = parseNoteEntries(result.yamlStr, issue.url)
- // Warn about headings that don't match any known feature heading or special section
+ // Unknown headings fall back to changes after case-insensitive correction fails.
const specialHeadings = ['Changes', 'Closing down', 'Retired']
const validHeadings = new Set([...featureHeadings, ...specialHeadings])
for (const entry of entries) {
if (!validHeadings.has(entry.heading)) {
- // Check for near-matches (case-insensitive)
const lowerHeading = entry.heading.toLowerCase()
const closeMatch = featureHeadings.find((h) => h.toLowerCase() === lowerHeading)
if (closeMatch) {
@@ -734,7 +684,7 @@ program
}
}
- // Dedup: avoid duplicate notes if the same issue was partially loaded from an existing file
+ // Avoid duplicates when an existing file already contributed the same issue note.
for (const entry of entries) {
const isDuplicate = allEntries.some(
(existing) =>
@@ -765,7 +715,7 @@ program
console.log(` Reason: ${skipReason}`)
} else {
spinner.fail(`${label} — ${msg.substring(0, 100)}`)
- // Show raw agent output only for real errors
+ // Show raw agent output only for real errors.
if (err.rawOutput) {
console.log('\n --- Raw agent output (last attempt) ---')
const truncated =
@@ -779,7 +729,6 @@ program
}
}
- // Step 4: Final summary.
flushBeforeExit = null
const newCount = allEntries.length - existingEntryCount
if (existingEntryCount > 0) {
@@ -802,7 +751,7 @@ program
process.exit(1)
}
if (singleIssue) {
- // For a single issue + stdout, print just the raw note YAML (not the full template)
+ // Single-issue stdout prints note entries, not the full release template.
const newEntries = allEntries.filter(
(e) => e.sourceUrl === `https://github.com/github/releases/issues/${singleIssue}`,
)
@@ -828,7 +777,7 @@ program
console.log('\nNo entries generated — no file written.')
}
- // Clean up stdin raw mode so the process can exit gracefully
+ // Clean up stdin raw mode so the process can exit gracefully.
if (process.stdin.isTTY) {
process.stdin.setRawMode(false)
process.stdin.pause()
diff --git a/src/ghes-releases/scripts/notify-release-pms.ts b/src/ghes-releases/scripts/notify-release-pms.ts
index 79adb25aad38..fb12bd9791ad 100644
--- a/src/ghes-releases/scripts/notify-release-pms.ts
+++ b/src/ghes-releases/scripts/notify-release-pms.ts
@@ -1,21 +1,10 @@
-/**
- * @purpose Writer tool
- * @description Notify PMs to review their GHES release notes on a PR
- *
- * Notify PMs about generated GHES release notes by posting a review comment
- * on each source release issue in github/releases.
- *
- * For each release issue URL found in the YAML file's `# https://...` comments,
- * this script posts a comment asking the PM to review the note in the PR and
- * react with 🚀 once satisfied.
- *
- * Usage:
- * # Post comments via GitHub Actions (handles auth automatically):
- * gh workflow run notify-release-pms.yml -f release=3.20 -f pr=12345
- *
- * # Preview locally (dry run, no token needed):
- * npm run notify-release-pms -- --release 3.20 --pr 12345 --dry-run
- */
+// @purpose Writer tool
+// @description Notify PMs to review their GHES release notes on a PR
+//
+// Posts docs-bot review comments on github/releases source issues from YAML source comments.
+// Product managers (PMs) review the PR and react with 🚀 when satisfied.
+// GitHub Actions usage: gh workflow run notify-release-pms.yml -f release=<release> -f pr=<pr>
+// Local preview: npm run notify-release-pms -- --release <release> --pr <pr> --dry-run
import { Command } from 'commander'
import { execFileSync } from 'child_process'
import fs from 'fs'
@@ -27,11 +16,7 @@ export interface SourceNote {
issueNumber: number
}
-/**
- * Run read-only `gh` CLI commands.
- * Uses DOCS_BOT_PAT_BASE when available (CI), otherwise falls back to
- * the caller's native `gh` auth (local).
- */
+// DOCS_BOT_PAT_BASE authenticates CI reads; caller gh auth handles local reads.
function ghRead(args: string[]): string {
const env = { ...process.env }
if (env.DOCS_BOT_PAT_BASE) {
@@ -46,10 +31,7 @@ function ghRead(args: string[]): string {
})
}
-/**
- * Run `gh` CLI commands authenticated as docs-bot (for posting comments).
- * Requires the DOCS_BOT_PAT_BASE environment variable to be set.
- */
+// Posting comments requires DOCS_BOT_PAT_BASE so they come from docs-bot.
function ghWrite(args: string[]): string {
const token = process.env.DOCS_BOT_PAT_BASE
if (!token) {
@@ -62,7 +44,7 @@ function ghWrite(args: string[]): string {
process.exit(1)
}
const env = { ...process.env, GH_TOKEN: token }
- // Ensure GH_TOKEN takes precedence over any pre-existing GITHUB_TOKEN
+ // GH_TOKEN must take precedence over any pre-existing GITHUB_TOKEN.
delete (env as Record<string, string | undefined>).GITHUB_TOKEN
return execFileSync('gh', args, {
encoding: 'utf8',
@@ -72,11 +54,7 @@ function ghWrite(args: string[]): string {
})
}
-/**
- * Parse release notes content and extract source issue URLs.
- * Each `# https://github.com/github/releases/issues/NNNN` comment
- * maps to the note(s) that follow it.
- */
+// Source issue URL comments attach each generated note to its github/releases issue.
export function parseSourceNotes(content: string): SourceNote[] {
const lines = content.split('\n')
const notes: SourceNote[] = []
@@ -86,8 +64,7 @@ export function parseSourceNotes(content: string): SourceNote[] {
const match = lines[i].match(/^\s*#\s*(https:\/\/github\.com\/github\/releases\/issues\/(\d+))/)
if (match) {
const issueNumber = parseInt(match[2], 10)
- // Some issues appear multiple times (e.g. in features and changes). Keep the
- // first occurrence so the link points to the primary note.
+ // Keep the first occurrence so duplicate issue links point to the primary note.
if (!seen.has(issueNumber)) {
seen.add(issueNumber)
notes.push({
@@ -116,8 +93,7 @@ export function buildCommentBody(
const prUrl = `https://github.com/github/docs-internal/pull/${prNumber}`
const fileUrl = `${prUrl}/files`
- // Use a marker so we can identify our comments later (for duplicate-prevention).
- // Include releaseType so RC and GA comments are distinguishable.
+ // Mark comments for duplicate detection; releaseType keeps RC and GA distinct.
const marker = buildMarker(version, releaseType.toLowerCase() as 'rc' | 'ga')
const mentions = assignees.length > 0 ? `${assignees.map((a) => `@${a}`).join(' ')} ` : ''
@@ -222,7 +198,7 @@ program
process.exit(1)
}
} else {
- // Auto-detect: prefer GA if it exists, otherwise RC (consistent with generate-release-notes)
+ // Auto-detect prefers GA over RC to match generate-release-notes.
if (fs.existsSync(gaPath)) {
rc = false
yamlPath = gaPath
@@ -239,7 +215,6 @@ program
const relativeFilePath = path.relative(process.cwd(), yamlPath)
- // Step 1: Extract source issue URLs.
spinner.start('Parsing release notes file...')
const sourceNotes = extractSourceNotes(yamlPath)
spinner.succeed(`Found ${sourceNotes.length} unique release issue(s) in ${relativeFilePath}`)
@@ -249,7 +224,6 @@ program
process.exit(0)
}
- // Step 2: Check for existing comments (avoid duplicates).
const releaseType = rc ? 'rc' : 'ga'
const marker = buildMarker(release, releaseType)
const alreadyCommented = new Set<number>()
@@ -268,7 +242,7 @@ program
alreadyCommented.add(note.issueNumber)
}
} catch {
- // If we can't read comments, we'll try to post and handle errors then
+ // Post anyway when comment reads fail; posting reports permission errors.
}
}
if (alreadyCommented.size > 0) {
@@ -282,7 +256,6 @@ program
spinner.succeed('No existing notifications found')
}
- // Step 3: Post comments.
const toNotify = sourceNotes.filter((n) => !alreadyCommented.has(n.issueNumber))
if (toNotify.length === 0) {
@@ -295,18 +268,17 @@ program
for (let i = 0; i < toNotify.length; i++) {
const note = toNotify[i]
- // Fetch assignees (or fall back to issue author) for the release issue
+ // Mention assignees, or the non-bot issue author when no assignee exists.
let assignees: string[] = []
try {
const raw = ghRead(['api', `repos/github/releases/issues/${note.issueNumber}`])
const issue = JSON.parse(raw)
assignees = (issue.assignees || []).map((a: { login: string }) => a.login)
- // Fall back to the issue author unless they're a bot
if (assignees.length === 0 && issue.user?.login && issue.user.type !== 'Bot') {
assignees = [issue.user.login]
}
} catch {
- // If we can't fetch the issue, post without mentions
+ // Post without mentions when the issue fetch fails.
}
const commentBody = buildCommentBody(release, rc, prNumber, assignees)
@@ -342,7 +314,6 @@ program
}
}
- // Summary.
console.log(`\n${'─'.repeat(40)}`)
console.log(`${dryRun ? '🔍 Dry run' : '✅ Done'}`)
console.log(
@@ -356,7 +327,7 @@ program
},
)
-// Only run CLI when executed directly (not when imported in tests)
+// Tests import helpers without running the CLI.
if (import.meta.url === `file://${process.argv[1]}`) {
program.parse(process.argv)
}
diff --git a/src/ghes-releases/scripts/release-banner.ts b/src/ghes-releases/scripts/release-banner.ts
index 7c2136cb64b4..64f15e74c3f1 100644
--- a/src/ghes-releases/scripts/release-banner.ts
+++ b/src/ghes-releases/scripts/release-banner.ts
@@ -1,12 +1,5 @@
-/**
- * @purpose Writer tool
- * @description Create or remove a release candidate banner for a GHES version
- */
-// [start-readme]
-//
-// This script creates or removes a release candidate banner for a specified version.
-//
-// [end-readme]
+// @purpose Writer tool
+// @description Create or remove a release candidate banner for a GHES version
import fs from 'fs/promises'
import { program } from 'commander'
diff --git a/src/ghes-releases/scripts/update-enterprise-dates.ts b/src/ghes-releases/scripts/update-enterprise-dates.ts
index 2eff3bc7c721..6a3a3bb12f1d 100644
--- a/src/ghes-releases/scripts/update-enterprise-dates.ts
+++ b/src/ghes-releases/scripts/update-enterprise-dates.ts
@@ -1,13 +1,9 @@
-/**
- * @purpose Writer tool
- * @description Update enterprise release dates from github/enterprise-releases
- */
-// [start-readme]
+// @purpose Writer tool
+// @description Update enterprise release dates from github/enterprise-releases
//
-// This script fetches data from https://github.com/github/enterprise-releases/blob/master/releases.json
-// and updates `src/ghes-releases/lib/enterprise-dates.json`, which the site uses for various functionality.
-//
-// [end-readme]
+// Fetches https://github.com/github/enterprise-releases/blob/master/releases.json
+// and updates src/ghes-releases/lib/enterprise-dates.json.
+// enterprise-dates.json supplies site release date behavior.
import { fileURLToPath } from 'url'
import path from 'path'
@@ -17,10 +13,11 @@ import { getContents } from '@/workflows/git-utils'
interface EnterpriseDates {
[releaseNumber: string]: {
- releaseDate: string // For backward compatibility - RC date initially, then GA date once available
+ // Keep releaseDate as the RC date until a GA date exists for backward compatibility.
+ releaseDate: string
deprecationDate: string
- releaseCandidateDate?: string // Release Candidate date
- generalAvailabilityDate?: string // General Availability date
+ releaseCandidateDate?: string
+ generalAvailabilityDate?: string
}
}
@@ -36,7 +33,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url))
const enterpriseDatesFile = path.join(__dirname, '../lib/enterprise-dates.json')
const enterpriseDatesString = await fs.readFile(enterpriseDatesFile, 'utf8')
-// check for required PAT
+// getContents requires GITHUB_TOKEN.
if (!process.env.GITHUB_TOKEN) {
throw new Error('Error! You must have a GITHUB_TOKEN set in an .env file to run this script.')
}
@@ -59,7 +56,7 @@ async function main(): Promise<void> {
const formattedDates: EnterpriseDates = {}
for (const [releaseNumber, releaseObject] of Object.entries(rawDates)) {
formattedDates[releaseNumber] = {
- // For backward compatibility, keep releaseDate as RC date initially, then GA date once available
+ // Keep releaseDate as the RC date until a GA date exists for backward compatibility.
releaseDate: releaseObject.release_candidate || releaseObject.start,
deprecationDate: releaseObject.end,
releaseCandidateDate: releaseObject.release_candidate,
diff --git a/src/ghes-releases/scripts/version-utils.ts b/src/ghes-releases/scripts/version-utils.ts
index 9e71b1d7cd63..f6fe47d63cdb 100644
--- a/src/ghes-releases/scripts/version-utils.ts
+++ b/src/ghes-releases/scripts/version-utils.ts
@@ -4,15 +4,12 @@ import { supported } from '@/versions/lib/enterprise-server-releases'
import getDataDirectory from '@/data-directory/lib/data-directory'
import { FeatureData, FrontmatterVersions } from '@/types'
-// Return true if lowestSupportedVersion > semVerRange
export function isGhesReleaseDeprecated(lowestSupportedVersion: string, semVerRange: string) {
const lowestSemver = semver.coerce(lowestSupportedVersion)
if (!lowestSemver) return false
return semver.gtr(lowestSemver.version, semVerRange)
}
-// Return true if the semver range is greater than the
-// lowest supported GHES version
export function isInAllGhes(semverRange: string) {
if (semverRange === '*') return true
const regexGt = /(>|>=){1}\s?(\d+\.\d+)/g
@@ -27,11 +24,8 @@ export function isInAllGhes(semverRange: string) {
return semver.lte(minVersion, oldestSupported)
}
-// A feature is deprecated if it only contains
-// GHES releases and all releases are deprecated
-// or all releases are supported.
+// GHES-only features disappear when their GHES range is fully deprecated.
export function isFeatureDeprecated(versions: FrontmatterVersions) {
- // All GHES releases are deprecated
return (
!!versions.ghes &&
!versions.fpt &&
@@ -40,8 +34,6 @@ export function isFeatureDeprecated(versions: FrontmatterVersions) {
)
}
-// Return true when the feature version is in all versions
-// and all GHES releases.
export function isAllVersions(versions: FrontmatterVersions) {
if (
versions &&
diff --git a/src/ghes-releases/tests/generate-release-notes.ts b/src/ghes-releases/tests/generate-release-notes.ts
index a656f6d0125d..02aee8cf6988 100644
--- a/src/ghes-releases/tests/generate-release-notes.ts
+++ b/src/ghes-releases/tests/generate-release-notes.ts
@@ -270,7 +270,6 @@ describe('buildReleaseNotesYaml', () => {
const reposIdx = yaml.indexOf('- heading: Repositories')
expect(actionsIdx).toBeGreaterThan(-1)
expect(reposIdx).toBeGreaterThan(-1)
- // GitHub Actions comes before Repositories in featureHeadings
expect(actionsIdx).toBeLessThan(reposIdx)
expect(yaml).toContain('Actions note.')
@@ -283,7 +282,6 @@ describe('buildReleaseNotesYaml', () => {
]
const yaml = buildReleaseNotesYaml(entries, false, featureHeadings)
- // Should appear under changes, not features
expect(yaml).toContain(' features:\n # TODO: Add feature notes')
expect(yaml).toContain(' changes:')
expect(yaml).toContain('# https://example.com/1')
@@ -305,7 +303,6 @@ describe('buildReleaseNotesYaml', () => {
expect(yaml).toContain('Deprecating X.')
expect(yaml).toContain(' retired:\n # https://example.com/2')
expect(yaml).toContain('Removed Y.')
- // Changes should be omitted since Closing down/Retired are excluded and no other entries exist
expect(yaml).not.toContain(' changes:')
})
@@ -314,8 +311,7 @@ describe('buildReleaseNotesYaml', () => {
expect(yaml).toContain('# TODO: Add feature notes')
expect(yaml).toContain('# TODO: Add known issues')
- // Empty changes, closing_down, and retired are omitted entirely
- // to avoid YAML parsing as null (which fails schema validation)
+ // Omit empty changes, closing_down, and retired so schema validation does not see null sections.
expect(yaml).not.toContain(' changes:')
expect(yaml).not.toContain(' closing_down:')
expect(yaml).not.toContain(' retired:')
diff --git a/src/ghes-releases/tests/notify-release-pms.ts b/src/ghes-releases/tests/notify-release-pms.ts
index d9e87a09cd8f..33eea75582e6 100644
--- a/src/ghes-releases/tests/notify-release-pms.ts
+++ b/src/ghes-releases/tests/notify-release-pms.ts
@@ -100,8 +100,7 @@ describe('buildCommentBody', () => {
})
describe('duplicate-prevention filtering', () => {
- // This tests the core filtering logic used in the CLI action:
- // const toNotify = sourceNotes.filter((n) => !alreadyCommented.has(n.issueNumber))
+ // These tests cover duplicate filtering without running the CLI action.
const sourceNotes: SourceNote[] = [
{ issueUrl: 'https://github.com/github/releases/issues/100', issueNumber: 100 },
@@ -133,7 +132,6 @@ describe('duplicate-prevention filtering', () => {
const marker = buildMarker('3.21', 'rc')
const commentBody = buildCommentBody('3.21', true, 100, ['octocat'])
- // Simulates the duplicate-check logic: comments.includes(marker)
expect(commentBody.includes(marker)).toBe(true)
})
@@ -145,7 +143,6 @@ describe('duplicate-prevention filtering', () => {
})
test('new issues added after initial run are not excluded', () => {
- // Simulates: ran script once for issues 100+200, then re-run after adding 300
const alreadyCommented = new Set([100, 200])
const updatedSourceNotes: SourceNote[] = [
...sourceNotes,
diff --git a/src/github-apps/lib/index.ts b/src/github-apps/lib/index.ts
index 9fef828acf55..cd3debd429fb 100644
--- a/src/github-apps/lib/index.ts
+++ b/src/github-apps/lib/index.ts
@@ -16,11 +16,10 @@ interface AppsConfig {
// parameter on getAppsData.
type AppsData = Record<string, unknown>
-// Deduplicated on-disk format types.
-// A leaf entry in the shared pool: an operation or permission object.
+// A shared pool entry contains one operation or permission object.
type SharedAppsEntry = Record<string, unknown>
-// Per-page index for permission pages: permName → metadata + indices into the pool.
+// Permission pages map each permission name to metadata and shared-entry indices.
interface PermissionsPageIndex {
[permName: string]: {
title: string
@@ -29,14 +28,14 @@ interface PermissionsPageIndex {
}
}
-// Per-page index for rest pages: category → indices into the pool.
+// REST pages map each category to shared-entry indices.
interface RestPageIndex {
[category: string]: number[]
}
type AppsPageIndex = PermissionsPageIndex | RestPageIndex
-// version-index.json: version → pageType → page index.
+// version-index.json maps each OpenAPI version and page type to a page index.
type AppsVersionIndex = Record<string, Record<string, AppsPageIndex>>
const logger = createLogger(import.meta.url)
@@ -48,9 +47,8 @@ let sharedEntries: SharedAppsEntry[] | null = null
let sharedVersionIndex: AppsVersionIndex | null = null
let sharedFormatAvailable: boolean | null = null
-// A missing shared-format file is expected (per-version files are the fallback),
-// but a corrupt or unparseable file should fail loudly rather than silently
-// degrade to the per-version files and hide bad generated data.
+// A missing shared-format file is expected because per-version files are the fallback.
+// Corrupt or unparseable files fail loudly instead of hiding bad generated data.
function isFileNotFoundError(err: unknown): boolean {
if (!(err instanceof Error) || !('code' in err)) return false
const code = (err as NodeJS.ErrnoException).code
@@ -66,8 +64,7 @@ function loadSharedAppsFormat(): boolean {
sharedVersionIndex = readCompressedJsonFileFallback(
path.join(ENABLED_APPS_DIR, 'version-index.json'),
) as AppsVersionIndex
- // Freeze pool data so reconstructed objects (which return references into
- // the pool) can't be mutated by downstream code and leak across versions.
+ // Freeze pool entries so downstream mutations cannot leak through shared version objects.
Object.freeze(sharedEntries)
for (const entry of sharedEntries) Object.freeze(entry)
sharedFormatAvailable = true
@@ -86,8 +83,7 @@ function loadSharedAppsFormat(): boolean {
return sharedFormatAvailable
}
-// Resolves a pool index into its entry, throwing a clear error if the index is
-// out of bounds (e.g. from a stale or corrupt version-index.json).
+// Resolve a pool index and report stale or corrupt version-index.json pointers.
function resolveSharedEntry(
idx: number,
pageType: string,
@@ -116,7 +112,6 @@ function reconstructAppsFromSharedFormat(
const isPermissions = pageType.includes('permissions')
if (isPermissions) {
- // Reconstruct permission data: { permName: { title, displayTitle, permissions: [...] } }
const result: Record<string, { title: string; displayTitle: string; permissions: unknown[] }> =
{}
for (const [permName, meta] of Object.entries(pageData as PermissionsPageIndex)) {
@@ -128,7 +123,6 @@ function reconstructAppsFromSharedFormat(
}
return result
} else {
- // Reconstruct rest data: { category: [...operations] }
const result: Record<string, unknown[]> = {}
for (const [category, indices] of Object.entries(pageData as RestPageIndex)) {
result[category] = indices.map((idx) => resolveSharedEntry(idx, pageType, openApiVersion))
@@ -137,8 +131,6 @@ function reconstructAppsFromSharedFormat(
}
}
-// Initialize the Map with the page type keys listed under `pages`
-// in the config.json file.
const appsDataConfig: AppsConfig = JSON.parse(
fs.readFileSync('src/github-apps/lib/config.json', 'utf8'),
)
@@ -161,8 +153,7 @@ export async function getAppsData<T extends AppsData = AppsData>(
if (data) {
pageTypeMap.set(openApiVersion, data)
} else {
- // Fall back to per-version JSON.
- // readCompressedJsonFileFallback checks for both a .br and a .json extension.
+ // Fall back to per-version .br or .json files when shared data is unavailable.
const appDataPath = path.join(ENABLED_APPS_DIR, openApiVersion, filename)
pageTypeMap.set(openApiVersion, readCompressedJsonFileFallback(appDataPath) as AppsData)
}
@@ -198,9 +189,7 @@ export async function getAppsServerSideProps(
const titles: string[] = useDisplayTitle
? Object.values(appsItems).map((item) => (item as AppsItemWithDisplayTitle).displayTitle!)
: Object.keys(appsItems)
- // getAutomatedPageMiniTocItems expects a `Context`, but this code path has
- // always passed Next.js's GetServerSidePropsContext at runtime.
- // Hence the double assertion.
+ // This path passes GetServerSidePropsContext where getAutomatedPageMiniTocItems expects Context.
const appMiniToc = await getAutomatedPageMiniTocItems(titles, context as unknown as Context)
if (appMiniToc) {
miniTocItems.push(...appMiniToc)
diff --git a/src/github-apps/scripts/enabled-list-schema.ts b/src/github-apps/scripts/enabled-list-schema.ts
index 75ee13712d98..11675dac0ee1 100644
--- a/src/github-apps/scripts/enabled-list-schema.ts
+++ b/src/github-apps/scripts/enabled-list-schema.ts
@@ -1,7 +1,6 @@
-// This schema is used to validate
-// src/github-apps/data/server-to-server-rest.json
-// src/github-apps/data/user-to-server-rest.json
-// and src/github-apps/data/fine-grained-pat.json
+// This schema validates src/github-apps/data/server-to-server-rest.json,
+// src/github-apps/data/user-to-server-rest.json,
+// and src/github-apps/data/fine-grained-pat.json.
interface SchemaProperty {
description: string
diff --git a/src/github-apps/scripts/permission-list-schema.ts b/src/github-apps/scripts/permission-list-schema.ts
index a30ecd52c2dc..b9d0cd1af105 100644
--- a/src/github-apps/scripts/permission-list-schema.ts
+++ b/src/github-apps/scripts/permission-list-schema.ts
@@ -1,6 +1,5 @@
-// This schema is used to validate
-// src/github-apps/data/fine-grained-pat-permissions.json
-// and src/github-apps/data/server-to-server-permissions.json
+// This schema validates src/github-apps/data/fine-grained-pat-permissions.json
+// and src/github-apps/data/server-to-server-permissions.json.
interface SchemaProperty {
type: string
@@ -49,7 +48,7 @@ const schema: Schema = {
type: 'object',
required: ['title', 'displayTitle', 'permissions'],
properties: {
- // Properties from the source OpenAPI schema that this module depends on
+ // Generated permission entries combine metadata titles with assembled permission rows.
title: {
description: 'The name of the permission.',
type: 'string',
diff --git a/src/github-apps/scripts/sync.ts b/src/github-apps/scripts/sync.ts
index b9c1f7d84ae7..22f26242bccd 100755
--- a/src/github-apps/scripts/sync.ts
+++ b/src/github-apps/scripts/sync.ts
@@ -13,7 +13,7 @@ import { validateJson } from '@/tests/lib/validate-json-schema'
const ENABLED_APPS_DIR = 'src/github-apps/data'
const CONFIG_FILE = 'src/github-apps/lib/config.json'
-// Actor type mapping from generic names to actual YAML values
+// Map generic actor names to excluded_actors values.
export const actorTypeMap: Record<string, string> = {
fine_grained_pat: 'fine_grained_personal_access_token',
server_to_server: 'github_app',
@@ -134,8 +134,7 @@ export async function syncGitHubAppsData(
for (const pageType of Object.keys(appsDataConfig.pages)) {
githubAppsData[pageType] = {}
}
- // Because the information used on the apps page doesn't require any
- // rendered content we can parse the dereferenced files directly
+ // Apps pages only need operation metadata here, so parse dereferenced OpenAPI files directly.
for (const [requestPath, operationsAtPath] of Object.entries(schemaData.paths)) {
for (const [verb, operation] of Object.entries(operationsAtPath)) {
if (!progAccessData[operation.operationId]) continue
@@ -191,12 +190,6 @@ export async function syncGitHubAppsData(
progAccessData[operation.operationId].permissions,
)
- // Filter out metadata permissions when combined with other permissions
- // The metadata permission is automatically granted with any other repository permission,
- // so documenting it for operations that require additional permissions is misleading.
- // This fixes the issue where mutating operations (PUT, DELETE) incorrectly appeared
- // to only need metadata access when they actually require write permissions.
- // See: https://github.com/github/docs-engineering/issues/5212
if (
shouldFilterMetadataPermission(
permissionName,
@@ -241,11 +234,7 @@ export async function syncGitHubAppsData(
const isExcluded = isActorExcluded(excludedActors, 'fine_grained_pat', actorTypeMap)
if (isFineGrainedPat && !isExcluded) {
- // Hardcoded exception: exclude repository_projects from fine-grained PAT permissions
- // This is because fine-grained PATs can only operate on organization-level Projects (classic),
- // not repository-level Projects (classic). Users cannot grant the repository Projects (classic)
- // fine-grained permission in the fine-grained PAT UI.
- // See: https://github.com/github/docs-engineering/issues/4613
+ // Fine-grained PATs grant org Projects (classic), not repo Projects (classic).
if (permissionName === 'repository_projects') {
continue
}
@@ -275,7 +264,6 @@ export async function syncGitHubAppsData(
const versionName = path.basename(schemaName, '.json')
const targetDirectory = path.join(ENABLED_APPS_DIR, versionName)
- // When a new version is added, we need to create the directory for it
if (!existsSync(targetDirectory)) {
await mkdir(targetDirectory, { recursive: true })
}
@@ -302,16 +290,16 @@ export async function syncGitHubAppsData(
await writeDeduplicatedAppsFormat()
}
+// The deduplicated format stores repeated operation and permission objects once.
+// version-index.json maps each version and page to those shared entries.
async function writeDeduplicatedAppsFormat() {
console.log(`\n▶️ Writing deduplicated GitHub Apps data...\n`)
- // Read all the per-version files we just wrote to build the shared format
const versions = fs.readdirSync(ENABLED_APPS_DIR).filter((f) => {
const fullPath = path.join(ENABLED_APPS_DIR, f)
return fs.statSync(fullPath).isDirectory() && f !== 'shared'
})
- // Pool for unique leaf objects (operations and permission entries)
const entriesPool: unknown[] = []
const entriesMap = new Map<string, number>()
@@ -324,9 +312,7 @@ async function writeDeduplicatedAppsFormat() {
return index
}
- // version-index structure:
- // For rest pages: { version: { pageType: { category: number[] } } }
- // For permission pages: { version: { pageType: { permName: { title, displayTitle, indices: number[] } } } }
+ // REST pages map categories to indices; permission pages map names to metadata and indices.
const versionIndex: Record<string, Record<string, unknown>> = {}
let totalItems = 0
@@ -339,9 +325,7 @@ async function writeDeduplicatedAppsFormat() {
const pageType = path.basename(file, '.json')
const data = JSON.parse(fs.readFileSync(path.join(versionDir, file), 'utf8'))
const isPermissions = pageType.includes('permissions')
-
if (isPermissions) {
- // Permission data: { permName: { title, displayTitle, permissions: [...] } }
const pageIndex: Record<
string,
{ title: string; displayTitle: string; indices: number[] }
@@ -359,7 +343,6 @@ async function writeDeduplicatedAppsFormat() {
}
versionIndex[version][pageType] = pageIndex
} else {
- // Rest data: { category: [...operations] }
const pageIndex: Record<string, number[]> = {}
for (const [category, operations] of Object.entries(
data as Record<string, AppDataOperation[]>,
@@ -547,7 +530,7 @@ export function calculateAdditionalPermissions(
)
}
-// Without this, a mutating operation appears to need only metadata access.
+// Metadata is redundant when any other permission applies, so hide it in those rows.
export function shouldFilterMetadataPermission(
permissionName: string,
permissionSets: Array<Record<string, string>>,
@@ -621,6 +604,7 @@ async function validateAppData(
}
}
+// Use gitHubSourceDirectory locally; use owner, repo, branch, and path remotely.
interface ProgActorResourceContentOptions {
owner?: string
repo?: string
@@ -629,11 +613,6 @@ interface ProgActorResourceContentOptions {
gitHubSourceDirectory?: string | null
}
-// When getting files from the GitHub repo locally (or in a Codespace)
-// you can pass the full or relative path to the `github` repository
-// directory on disk.
-// When the source directory is `rest-api-description` (which is more common)
-// you can pass the `owner`, `repo`, `branch`, and `path` (repository path)
async function getProgActorResourceContent({
owner,
repo,
diff --git a/src/github-apps/tests/deduplication.ts b/src/github-apps/tests/deduplication.ts
index 3a2503bec523..53cb5756b8dd 100644
--- a/src/github-apps/tests/deduplication.ts
+++ b/src/github-apps/tests/deduplication.ts
@@ -146,7 +146,7 @@ describe('GitHub Apps deduplication', () => {
}
const uniqueEntries = entries.length
- // We expect at least 70% dedup rate based on issue analysis (~84% reported)
+ // The 70% threshold leaves room for normal generated-data churn.
const dedupRate = 1 - uniqueEntries / totalReferences
expect(dedupRate).toBeGreaterThan(0.7)
})
diff --git a/src/github-apps/tests/excluded-actors.ts b/src/github-apps/tests/excluded-actors.ts
index 7cbaa790f24e..3041a1652146 100644
--- a/src/github-apps/tests/excluded-actors.ts
+++ b/src/github-apps/tests/excluded-actors.ts
@@ -44,8 +44,6 @@ describe('excluded_actors filtering', () => {
expect(isActorExcluded(['UserProgrammaticAccess'], 'fine_grained_pat', actorTypeMap)).toBe(true)
expect(isActorExcluded(['github_app'], 'server_to_server', actorTypeMap)).toBe(true)
expect(isActorExcluded(['user_access_token'], 'user_to_server', actorTypeMap)).toBe(true)
-
- // Test fallback when no mapping exists
expect(isActorExcluded(['some_unmapped_actor'], 'some_unmapped_actor')).toBe(true)
expect(isActorExcluded(['some_unmapped_actor'], 'different_actor')).toBe(false)
})
@@ -84,8 +82,6 @@ describe('excluded_actors filtering', () => {
).toBe(true)
expect(isActorExcluded(['github_app'], 'server_to_server', actorTypeMap)).toBe(true)
expect(isActorExcluded(['user_access_token'], 'user_to_server', actorTypeMap)).toBe(true)
-
- // Test fallback when no mapping exists
expect(isActorExcluded(['some_unmapped_actor'], 'some_unmapped_actor')).toBe(true)
expect(isActorExcluded(['some_unmapped_actor'], 'different_actor')).toBe(false)
})
diff --git a/src/github-apps/tests/metadata-permissions.ts b/src/github-apps/tests/metadata-permissions.ts
index 3bdc2e025b9a..a644ab30629a 100644
--- a/src/github-apps/tests/metadata-permissions.ts
+++ b/src/github-apps/tests/metadata-permissions.ts
@@ -191,12 +191,11 @@ describe('metadata permissions filtering', () => {
expect(shouldFilterMetadataPermission('metadata', metadataInSeparateSet)).toBe(true)
})
+ // PUT and DELETE /orgs/{org}/actions/permissions/repositories/{repository_id}
+ // pair metadata with organization_administration.
test('filters metadata permissions that match the GitHub issue examples', () => {
- // These are examples from the GitHub issue that should be filtered out
- // PUT /orgs/{org}/actions/permissions/repositories/{repository_id}
const putActionsPermissions = [{ metadata: 'read', organization_administration: 'write' }]
- // DELETE /orgs/{org}/actions/permissions/repositories/{repository_id}
const deleteActionsPermissions = [{ metadata: 'read', organization_administration: 'write' }]
expect(shouldFilterMetadataPermission('metadata', putActionsPermissions)).toBe(true)
@@ -278,12 +277,9 @@ describe('metadata permissions filtering', () => {
}
})
+ // PUT and DELETE /orgs/{org}/actions/permissions/repositories/{repository_id}
+ // pair metadata with organization_administration.
test('validates filtering logic matches expected behavior from issue', () => {
- // Based on the GitHub issue, these operations should be filtered out from metadata:
- // - PUT /orgs/{org}/actions/permissions/repositories/{repository_id}
- // - DELETE /orgs/{org}/actions/permissions/repositories/{repository_id}
- // Because they have metadata + organization_administration permissions
-
const progData: ProgAccessData = {
userToServerRest: true,
serverToServer: true,
diff --git a/src/github-apps/tests/rendering.ts b/src/github-apps/tests/rendering.ts
index 19ebb9ca7e78..fc3b249cb2ff 100644
--- a/src/github-apps/tests/rendering.ts
+++ b/src/github-apps/tests/rendering.ts
@@ -70,7 +70,6 @@ describe('REST references docs', () => {
apiVersion,
)
- // using the static file, generate the expected slug for each operation
for (const [key, value] of Object.entries(enabledForApps)) {
schemaSlugs.push(
...value.map(
@@ -81,7 +80,6 @@ describe('REST references docs', () => {
),
)
}
- // get all of the href attributes in the anchor tags
const contentPath = configContent.pages[page].targetFilename
.replace('content/', '')
.replace('.md', '')
@@ -94,7 +92,6 @@ describe('REST references docs', () => {
})
test('loads permission list pages', async () => {
- // permissions pages
for (const page of permissionPages) {
const schemaSlugs: string[] = []
@@ -104,7 +101,6 @@ describe('REST references docs', () => {
apiVersion,
)
- // using the static file, generate the expected slug for each operation
for (const value of Object.values(permissionsData)) {
schemaSlugs.push(
...value.permissions.map(
@@ -116,7 +112,6 @@ describe('REST references docs', () => {
)
}
- // get all of the href attributes in the anchor tags
const contentPath = configContent.pages[page].targetFilename
.replace('content/', '')
.replace('.md', '')
diff --git a/src/github-apps/tests/sync.ts b/src/github-apps/tests/sync.ts
index ec8dad3f1810..2b412bf07141 100644
--- a/src/github-apps/tests/sync.ts
+++ b/src/github-apps/tests/sync.ts
@@ -128,7 +128,7 @@ describe('getProgAccessData', () => {
const expectedData = {
userToServerRest: false,
serverToServer: true,
- fineGrainedPat: false, // false because user_to_server.enabled is false
+ fineGrainedPat: false, // user_to_server.enabled is false
permissions: [{ metadata: 'read' }],
allowPermissionlessAccess: true,
allowsPublicRead: false,
@@ -158,7 +158,6 @@ describe('getProgAccessData', () => {
const result = await processProgAccessDataMock(mockProgAccessDataRaw, mockProgActorResources)
- // All operation IDs should exist (whitespace should be trimmed)
expect(result.progAccessData).toHaveProperty('operation-a')
expect(result.progAccessData).toHaveProperty('operation-b')
expect(result.progAccessData).toHaveProperty('operation-c')
@@ -224,7 +223,7 @@ describe('getProgAccessData', () => {
const expectedCommaData = {
userToServerRest: true,
serverToServer: false,
- fineGrainedPat: false, // false because disabled_for_patv2 is true
+ fineGrainedPat: false, // disabled_for_patv2 is true
permissions: [{ metadata: 'write' }],
allowPermissionlessAccess: true,
allowsPublicRead: false,
@@ -236,8 +235,6 @@ describe('getProgAccessData', () => {
})
})
-// Helper function to simulate the data processing logic from sync.ts
-// without needing to set up the full file system or remote API calls
async function processProgAccessDataMock(
progAccessDataRaw: ProgAccessDataRaw[],
progActorResources: ProgActorResources,
@@ -255,7 +252,6 @@ async function processProgAccessDataMock(
basicAuth: operation.basic_auth,
}
- // Handle comma-separated operation IDs
const operationIds = operation.operation_ids.split(',').map((id) => id.trim())
for (const operationId of operationIds) {
progAccessData[operationId] = operationData
diff --git a/src/journeys/components/JourneyTrackNav.tsx b/src/journeys/components/JourneyTrackNav.tsx
index 0a8923691aa8..f940fbc01b72 100644
--- a/src/journeys/components/JourneyTrackNav.tsx
+++ b/src/journeys/components/JourneyTrackNav.tsx
@@ -16,8 +16,7 @@ export function JourneyTrackNav({ context }: Props) {
const upNext = nextGuide ?? nextTrackFirstGuide
if (!upNext) return null
- // In-track, show the next article's title.
- // Crossing tracks, show the track name so the reader knows they're moving on.
+ // Crossing tracks uses the track name so readers know they are moving to another track.
const label = nextGuide ? nextGuide.title : nextTrackFirstGuide!.trackTitle
const progress = t('up_next_progress')
diff --git a/src/journeys/lib/journey-path-resolver.ts b/src/journeys/lib/journey-path-resolver.ts
index 566199827fbd..ecb1640357a3 100644
--- a/src/journeys/lib/journey-path-resolver.ts
+++ b/src/journeys/lib/journey-path-resolver.ts
@@ -59,9 +59,8 @@ type JourneyPage = {
}>
}
-// All computed once, on first use.
-// Guide hrefs containing Liquid can't be resolved ahead of time,
-// so they're absent from cachedGuidePaths and set hasDynamicGuides instead.
+// Static guide paths cache on first use.
+// Rendered hrefs stay out of cachedGuidePaths and set hasDynamicGuides.
let cachedJourneyPages: JourneyPage[] | null = null
let cachedGuidePaths: Set<string> | null = null
let hasDynamicGuides = false
@@ -134,9 +133,7 @@ async function fetchGuideData(
return null
}
-/**
- * Returns null if the article isn't a guide in any journey track.
- */
+// Returns null when no journey track applies to the article and current version.
export async function resolveJourneyContext(
articlePath: string,
pages: Record<string, Page>,
@@ -159,8 +156,7 @@ export async function resolveJourneyContext(
for (const journeyPage of journeyPages) {
if (!journeyPage.journeyTracks) continue
- // Track articles inherit the landing page's versions,
- // so a journey that doesn't apply to the current version has no navigation to show.
+ // Track articles inherit landing page versions, so unmatched versions show no navigation.
if (journeyPage.versions) {
const journeyVersions = getApplicableVersions(journeyPage.versions)
if (!journeyVersions.includes(context.currentVersion || '')) {
@@ -187,8 +183,7 @@ export async function resolveJourneyContext(
() => guidePath,
)
} catch {
- // executeWithFallback rethrows errors it can't fall back from,
- // such as any error in English.
+ // executeWithFallback rethrows non-fallbackable errors and all English content errors.
renderedGuidePath = guidePath
}
}
@@ -205,7 +200,7 @@ export async function resolveJourneyContext(
const alternativeNextStep = track.guides[guideIndex].alternativeNextStep || ''
let renderedAlternativeNextStep = alternativeNextStep
- // Rendered with links intact, unlike the hrefs above which use textOnly.
+ // Render this with links intact, unlike the hrefs above that use textOnly.
if (needsRendering(alternativeNextStep)) {
try {
renderedAlternativeNextStep = await executeWithFallback(
@@ -218,8 +213,7 @@ export async function resolveJourneyContext(
}
}
- // fetchGuideData returns null for guides missing in the current version.
- // Dropping them keeps the counts and prev/next links correct.
+ // Drop guides that fail lookup so counts and prev/next links use resolvable guides.
const availableGuides = (
await Promise.all(
track.guides.map(async (guide, i) => {
@@ -285,9 +279,7 @@ export async function resolveJourneyContext(
return result
}
-/**
- * Reads journey tracks from frontmatter, rendering any Liquid they contain.
- */
+// Journey track frontmatter may contain Liquid, so render it before components use it.
export async function resolveJourneyTracks(
journeyTracks: JourneyPage['journeyTracks'],
context: Context,
diff --git a/src/journeys/middleware/journey-track.ts b/src/journeys/middleware/journey-track.ts
index dd06002faa59..5e63d0f5ab14 100644
--- a/src/journeys/middleware/journey-track.ts
+++ b/src/journeys/middleware/journey-track.ts
@@ -38,12 +38,11 @@ export default async function journeyTrack(
if (page.journeyTracks) {
const resolvedTracks = await resolveJourneyTracks(page.journeyTracks, req.context)
- // Read later by getServerSideProps.
+ // getServerSideProps reads resolvedJourneyTracks from the page object.
page.resolvedJourneyTracks = resolvedTracks
}
- // Unconditional, because guide articles need this
- // even though they carry no journeyTracks of their own.
+ // Resolve every article because guide pages do not carry their own journeyTracks.
const journeyContext = await resolveJourneyContext(
req.pagePath || '',
req.context.pages || {},
diff --git a/src/journeys/tests/journey-path-resolver.ts b/src/journeys/tests/journey-path-resolver.ts
index e037a54309b0..e7afb804e4ad 100644
--- a/src/journeys/tests/journey-path-resolver.ts
+++ b/src/journeys/tests/journey-path-resolver.ts
@@ -4,8 +4,7 @@ import { resolveJourneyContext, resolveJourneyTracks } from '../lib/journey-path
import getLinkData from '@/journeys/lib/get-link-data'
import type { Page } from '@/types'
-// Mock modules since we just want to test journey functions, not their dependencies or
-// against real content files
+// Mock dependencies so journey functions run without real content files.
vi.mock('@/journeys/lib/get-link-data', () => ({
default: vi.fn(async (rawLinks: string | string[] | undefined) => {
const path = Array.isArray(rawLinks) ? rawLinks[0] : rawLinks
@@ -191,7 +190,6 @@ describe('journey-path-resolver', () => {
mockContext,
)
- // This should find the same track as the version with leading slash
expect(result?.trackId).toBe('getting_started')
expect(result?.currentGuideIndex).toBe(1)
})
@@ -235,7 +233,7 @@ describe('journey-path-resolver', () => {
test('renders liquid templates in titles and descriptions', async () => {
const result = await resolveJourneyTracks(mockJourneyTracks, mockContext)
- // Should return the content as-is since our mock renderContent is a passthrough
+ // The mock renderContent returns input unchanged.
expect(result[0].title).toBe(
'Getting started with {% data variables.product.company_short %}',
)
@@ -252,15 +250,14 @@ describe('journey-path-resolver', () => {
expect(result[0].timeCommitment).toBe('{% data variables.product.company_short %} 2-4 hours')
expect(result[1].timeCommitment).toBe('4-6 hours')
- // The Liquid-bearing timeCommitment should be rendered with { textOnly: true },
- // matching how title/description are rendered.
+ // Liquid timeCommitment renders with textOnly, matching titles and descriptions.
const timeCommitmentCall = mockRenderContent.mock.calls.find(
([content]) => content === '{% data variables.product.company_short %} 2-4 hours',
)
expect(timeCommitmentCall).toBeDefined()
expect(timeCommitmentCall?.[2]).toEqual({ textOnly: true })
- // Plain (non-Liquid) timeCommitment should not be sent through renderContent
+ // Plain timeCommitment skips renderContent.
const plainCall = mockRenderContent.mock.calls.find(([content]) => content === '4-6 hours')
expect(plainCall).toBeUndefined()
})
diff --git a/src/languages/lib/correct-translation-content.ts b/src/languages/lib/correct-translation-content.ts
index d7966b6a3598..b93717184066 100644
--- a/src/languages/lib/correct-translation-content.ts
+++ b/src/languages/lib/correct-translation-content.ts
@@ -1811,6 +1811,8 @@ export function correctTranslatedContentStrings(
content = content.replaceAll('<b></b>', '')
content = content.replaceAll('<u></u>', '')
+ content = content.replace(/<\/?c\d+\s*\/?>/g, '')
+
content = content.replace(/(\{%-? )ifversion-([a-z][\w-]*\s*%\})/g, '$1ifversion $2')
content = content.replaceAll('["AUTOTITLE]', '"[AUTOTITLE]')
diff --git a/src/languages/tests/correct-translation-content.ts b/src/languages/tests/correct-translation-content.ts
index 5a49ba4c2cdb..485d5778cec9 100644
--- a/src/languages/tests/correct-translation-content.ts
+++ b/src/languages/tests/correct-translation-content.ts
@@ -2998,6 +2998,32 @@ Para más información, consulta "[AUTOTITLE](/path)".
})
})
+ describe('universal: strips leftover CAT-tool <cN> placeholder tags', () => {
+ test('strips paired <c0>...</c0> tags around text', () => {
+ expect(fix('Use the <c0>Create an issue</c0> endpoint.', 'es')).toBe(
+ 'Use the Create an issue endpoint.',
+ )
+ })
+
+ test('strips self-closing <c0/> and unmatched closing tags', () => {
+ expect(fix('See the note.<c0/> More text.</c1>', 'ja')).toBe('See the note. More text.')
+ })
+
+ test('strips nested and numbered <cN> tags', () => {
+ expect(
+ fix(
+ '<c1>repositorio especificado octocat/Spoon-Knife<c3>.<c4> Reemplace `REPO-NAME`',
+ 'es',
+ ),
+ ).toBe('repositorio especificado octocat/Spoon-Knife. Reemplace `REPO-NAME`')
+ })
+
+ test('leaves content without <cN> tags unchanged', () => {
+ const correct = 'Use the Create an issue endpoint.'
+ expect(fix(correct, 'es')).toBe(correct)
+ })
+ })
+
describe('ja: github-token-scope-descriptions.md per-file fix', () => {
test('restores the missing endif in the security-events row', () => {
const broken =
diff --git a/src/observability/lib/failbot.ts b/src/observability/lib/failbot.ts
index e2b90878c26e..dbd89c203edb 100644
--- a/src/observability/lib/failbot.ts
+++ b/src/observability/lib/failbot.ts
@@ -26,6 +26,8 @@ async function retryingFetch(input: RequestInfo | URL, init?: RequestInit): Prom
return response
}
+// Failbot additional_data only accepts flat string and number values, so keep requestUuid.
+// https://github.com/github/failbotg/blob/main/docs/api.md#additional-data
export function report(error: Error, metadata?: Record<string, unknown>) {
if (!process.env.HAYSTACK_URL) {
return
@@ -42,9 +44,6 @@ export function report(error: Error, metadata?: Record<string, unknown>) {
backends,
})
- // Metadata can only be a flat object with string & number values,
- // so only add the requestUuid.
- // https://github.com/github/failbotg/blob/main/docs/api.md#additional-data
const loggerContext = getLoggerContext()
return failbot.report(error, {
@@ -53,7 +52,7 @@ export function report(error: Error, metadata?: Record<string, unknown>) {
})
}
-// Kept so legacy callers can keep doing `FailBot.report(myError)`.
+// Preserves FailBot.report(error) for existing callers.
export default {
report,
}
diff --git a/src/observability/lib/handle-package-not-found.ts b/src/observability/lib/handle-package-not-found.ts
index 8bb738532c08..80c6c122d19b 100644
--- a/src/observability/lib/handle-package-not-found.ts
+++ b/src/observability/lib/handle-package-not-found.ts
@@ -1,14 +1,8 @@
-/*
-This file adds a custom error message if a package is missing
-to prompt the contributor to run `npm ci`.
-This handler must be separate from handle-exceptions.ts in order to function.
-It's imported in package.json in nodemonConfig,
-whereas that is imported in start-server.ts.
-This file must not import any packages.
-We are suggesting `npm ci` to contributors
-to avoid unexpected changes to the package-lock.json file.
-All other errors should fall through to the error handler in handle-exceptions.ts.
-*/
+// Shows a custom npm ci prompt for missing-package errors.
+// Recommend npm ci instead of npm install to avoid unexpected package-lock.json changes.
+// package.json loads this file through nodemonConfig before start-server.ts loads handle-exceptions.ts.
+// Keep it dependency-free so missing packages can reach this handler.
+// Other uncaught exceptions fall through to handle-exceptions.ts.
type ErrorWithCode = {
code: string
diff --git a/src/observability/lib/runtime-metrics.ts b/src/observability/lib/runtime-metrics.ts
index 42740357f5af..695681cceefa 100644
--- a/src/observability/lib/runtime-metrics.ts
+++ b/src/observability/lib/runtime-metrics.ts
@@ -1,13 +1,7 @@
-/**
- * Periodically emits Node.js runtime metrics to Datadog via StatsD.
- *
- * Covers three categories that are otherwise invisible:
- * 1. V8 heap: used vs limit, so we can spot memory pressure before OOMs.
- * 2. GC: pause duration, so we can correlate latency spikes with GC.
- * 3. Event-loop delay: p50/p99, so we can see when the loop is blocked.
- *
- * Only activates when StatsD is sending real metrics (MODA_PROD_SERVICE_ENV).
- */
+// Emits runtime metrics that StatsD does not capture elsewhere:
+// V8 heap usage and limit for memory pressure, GC pause duration for latency correlation,
+// and event-loop p50 and p99 delay for blocked-loop detection.
+// Starts only when StatsD sends real metrics through MODA_PROD_SERVICE_ENV.
import v8 from 'node:v8'
import { monitorEventLoopDelay, PerformanceObserver } from 'node:perf_hooks'
@@ -21,9 +15,7 @@ function isMetricsEnabled(): boolean {
return process.env.MODA_PROD_SERVICE_ENV === 'true' && process.env.NODE_ENV !== 'test'
}
-/**
- * Call once at server start. Safe to call multiple times (no-op after first).
- */
+// Safe to call from multiple server-start paths; calls after the first are no-ops.
export function startRuntimeMetrics(): void {
if (started) return
started = true
@@ -43,8 +35,7 @@ export function startRuntimeMetrics(): void {
const gcObserver = new PerformanceObserver((list) => {
for (const entry of list.getEntries()) {
const kind = (entry as unknown as { detail?: { kind?: number } }).detail?.kind
- // kind: 1 = Scavenge (minor), 2 = Mark-Sweep-Compact (major),
- // 4 = Incremental marking, 8 = Process weak callbacks, 15 = All
+ // perf_hooks GC kinds: 1 minor, 4 major, 8 incremental, 16 weak callbacks.
const tag = kind === 1 ? 'minor' : kind === 2 ? 'major' : 'other'
statsd.histogram('node.gc.pause', entry.duration, [`gc_type:${tag}`])
}
diff --git a/src/observability/lib/statsd.ts b/src/observability/lib/statsd.ts
index ff8254d18ffe..5690a54237df 100644
--- a/src/observability/lib/statsd.ts
+++ b/src/observability/lib/statsd.ts
@@ -11,17 +11,15 @@ const {
const mock = NODE_ENV === 'test' || MODA_PROD_SERVICE_ENV !== 'true'
-// MODA_APP_NAME gets set when the deploy target is Moda
+// Moda deploys set MODA_APP_NAME for tagging.
const modaApp = MODA_APP_NAME ? `moda_app_name:${MODA_APP_NAME}` : false
const tagCandidates = ['app:docs', modaApp]
export const tags: string[] = tagCandidates.filter((tag): tag is string => Boolean(tag))
const statsd = new StatsD({
- // hot-shots falls back to DD_AGENT_HOST and DD_DOGSTATSD_PORT,
- // then to localhost:8125.
- // Moda defines DD_DOGSTATSD_PORT but not DD_AGENT_HOST,
- // and needs the host set to the Kubernetes node name from KUBE_NODE_HOSTNAME.
+ // hot-shots falls back to localhost:8125 when neither host variable is set.
+ // Moda sets only DD_DOGSTATSD_PORT, so use KUBE_NODE_HOSTNAME as the DogStatsD host.
host: DD_AGENT_HOST || KUBE_NODE_HOSTNAME,
port: DD_DOGSTATSD_PORT ? parseInt(DD_DOGSTATSD_PORT, 10) : undefined,
prefix: 'docs.',
@@ -31,10 +29,8 @@ const statsd = new StatsD({
export default statsd
-// hot-shots v14 changed asyncTimer/timer to inject a TimerContext as the
-// final argument of the wrapped function. This adapter lets callers keep
-// passing functions with their original signatures by appending an ignored
-// TimerContext parameter.
+// hot-shots asyncTimer and timer append TimerContext to wrapped functions.
+// This adapter preserves callers' original signatures by dropping that extra argument.
export function adaptForTimer<P extends unknown[], R>(
fn: (...args: P) => Promise<R>,
): (...args: [...P, TimerContext]) => Promise<R> {
diff --git a/src/observability/lib/tracing.browser.ts b/src/observability/lib/tracing.browser.ts
index c9413916387a..4eb75bd8ce42 100644
--- a/src/observability/lib/tracing.browser.ts
+++ b/src/observability/lib/tracing.browser.ts
@@ -1,3 +1 @@
-// Browser stub for tracing.ts: OTel is server-only.
-// This file is aliased in by Next.js webpack and Turbopack for client bundles.
-// It's a no-op: tracing.ts is a side-effect-only module with no exports.
+// Next.js aliases tracing.ts to this empty client-bundle stub because tracing is server-only.
diff --git a/src/observability/lib/tracing.ts b/src/observability/lib/tracing.ts
index 91f4e9ecb874..524a0b77db32 100644
--- a/src/observability/lib/tracing.ts
+++ b/src/observability/lib/tracing.ts
@@ -1,18 +1,10 @@
-// OpenTelemetry distributed tracing setup for docs-internal,
-// following the same pattern as github/alloy and github/github-ui.
-//
-// The instrumentation list (HTTP, Express, Undici/fetch) is explicit
-// instead of `getNodeAutoInstrumentations()`.
-// The "auto" helper enables ~30 instrumentations,
-// including ones that patch Node core modules (`fs`, `net`, `dns`) on every server.
-// Several of these are known to cause performance and listener-leak issues,
-// and OTel itself recommends disabling `instrumentation-fs` in production.
-// We only have HTTP traffic and outbound fetch in this app,
-// so we wire those up explicitly.
-//
-// References:
-// - https://thehub.github.com/epd/engineering/dev-practicals/observability/distributed-tracing/
-// - https://thehub.github.com/epd/engineering/dev-practicals/observability/distributed-tracing/github-telemetry-js-user-guide/
+// Follows the github/alloy and github/github-ui tracing pattern.
+// Uses explicit HTTP, Express, and Undici instrumentation instead of getNodeAutoInstrumentations.
+// The auto helper enables about 30 instrumentations, including fs, net, and dns patches.
+// These can hurt performance or leak listeners; OTel recommends disabling instrumentation-fs in production.
+// This app only needs inbound HTTP and outbound fetch tracing.
+// See https://thehub.github.com/epd/engineering/dev-practicals/observability/distributed-tracing/
+// See https://thehub.github.com/epd/engineering/dev-practicals/observability/distributed-tracing/github-telemetry-js-user-guide/
import {
CompositePropagator,
@@ -51,7 +43,7 @@ if (process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT) {
})
}
- // Uses `once` to prevent duplicate shutdown if SIGTERM is delivered multiple times.
+ // once prevents duplicate shutdown when SIGTERM arrives more than once.
process.once('SIGTERM', async () => {
try {
await sdk.shutdown()
diff --git a/src/observability/logger/index.ts b/src/observability/logger/index.ts
index 3495a799c2d0..d7cf8ff87288 100644
--- a/src/observability/logger/index.ts
+++ b/src/observability/logger/index.ts
@@ -45,7 +45,7 @@ function formatContext(ctx: Record<string, unknown>): string {
return parts.length > 0 ? ` ${parts.join(' ')}` : ''
}
-// Handles file:// URLs (from import.meta.url) and plain string labels.
+// Accepts file URLs from import.meta.url and plain string labels.
function resolveFilePath(filePath: string): string {
try {
const parsed = new URL(filePath)
@@ -76,13 +76,8 @@ interface LoggerMethod {
(message: string, ...args: (string | number | boolean | Error | IncludeContext | object)[]): void
}
-/*
-Call this function with `import.meta.url` as the argument to create a logger for a specific file.
-
-e.g. `const logger = createLogger(import.meta.url)`
-
-Logs will be output to the console in development, and in `logfmt` format to stdout in production.
-*/
+// Pass import.meta.url so logs identify the caller file.
+// Development logs go to console; production logs use logfmt on stdout.
export function createLogger(filePath: string) {
if (!filePath) {
throw new Error('createLogger must be called with the import.meta.url argument')
@@ -151,7 +146,7 @@ export function createLogger(filePath: string) {
}
const currentLogLevel = getLogLevelNumber()
if (LOG_LEVELS[level] > currentLogLevel) {
- return // Do not log if the requested level is lower priority
+ return // Higher numbers are more verbose.
}
const loggerContext = getLoggerContext()
@@ -171,7 +166,7 @@ export function createLogger(filePath: string) {
const includedContextWithFormattedError = {} as IncludeContext
for (const [key, value] of Object.entries(includeContext)) {
if (typeof value === 'object' && value instanceof Error) {
- // Errors don't serialize well to JSON, so just log the message + stack trace
+ // Errors need explicit fields because JSON serialization drops message and stack.
includedContextWithFormattedError[key] = value.message
includedContextWithFormattedError[`${key}_code`] = (value as NodeJS.ErrnoException).code
includedContextWithFormattedError[`${key}_name`] = value.name
diff --git a/src/observability/logger/lib/log-levels.ts b/src/observability/logger/lib/log-levels.ts
index fcf3fd40a419..5e63c3b14e7c 100644
--- a/src/observability/logger/lib/log-levels.ts
+++ b/src/observability/logger/lib/log-levels.ts
@@ -1,8 +1,5 @@
-/*
-The log level is controlled by the `LOG_LEVEL` environment variable, where lower
-log levels = more verbose. If log level is 'info', only 'info', 'warn', and
-'error' logs are output.
-*/
+// LOG_LEVEL controls verbosity. Lower numbers are higher priority.
+// For LOG_LEVEL=info, info, warn, and error logs are emitted.
export const LOG_LEVELS = {
error: 0,
warn: 1,
@@ -17,10 +14,8 @@ function isValidLogLevel(level: string): level is LogLevel {
return level in LOG_LEVELS
}
-// Defaults when LOG_LEVEL isn't set:
-// - 'info' in development
-// - 'debug' in production
-// - 'debug' in test, because `vitest` turns off logs unless --silent=false is passed
+// Default LOG_LEVEL is info in development and debug in production.
+// Tests default to debug because vitest suppresses logs unless --silent=false is passed.
export function getLogLevelNumber(): LogLevelValue {
let defaultLogLevel: LogLevel = 'info'
if (
diff --git a/src/observability/logger/lib/logger-context.ts b/src/observability/logger/lib/logger-context.ts
index baff1072e685..07b07308b334 100644
--- a/src/observability/logger/lib/logger-context.ts
+++ b/src/observability/logger/lib/logger-context.ts
@@ -1,9 +1,7 @@
import { AsyncLocalStorage } from 'async_hooks'
import type { NextFunction, Request, Response } from 'express'
-// Think of this like a Redux store, but for the backend.
-// An early middleware calls asyncLocalStorage.run(store, ...),
-// which lets all downstream middleware read the store via `getLoggerContext`.
+// AsyncLocalStorage carries request fields from early middleware to downstream log calls.
export const asyncLocalStorage = new AsyncLocalStorage()
export type LoggerContext = {
@@ -43,19 +41,14 @@ export function updateLoggerContext(newContext: Partial<LoggerContext>): void {
}
const INCLUDE_HEADERS = [
- // Device / UA
'user-agent',
'sec-ch-ua',
'sec-ch-ua-platform',
- // Language
'x-user-language',
'accept-language',
- // Version
'x-user-version',
- // Host
'host',
'x-host',
- // Cache control
'cache-control',
]
diff --git a/src/observability/logger/lib/to-logfmt.ts b/src/observability/logger/lib/to-logfmt.ts
index c1b5f1648243..fd0f06574818 100644
--- a/src/observability/logger/lib/to-logfmt.ts
+++ b/src/observability/logger/lib/to-logfmt.ts
@@ -1,18 +1,5 @@
-/*
- Flattens a JSON object and converts it to a logfmt string
- Nested objects are flattened with a dot separator, e.g. requestContext.path=/en
- This is because Splunk doesn't support nested JSON objects.
-
- Example
- {
- "a": 1,
- "b": {
- "c": 2
- }
- }
- becomes
- a=1 b.c=2
-*/
+// Flattens nested context for Splunk, which cannot query nested JSON objects.
+// Example: { requestContext: { path: "/en" } } becomes requestContext.path=/en.
// Matches the original node-logfmt library's quoting and escaping behavior.
function stringify(data: Record<string, unknown>): string {
@@ -46,7 +33,6 @@ function stringify(data: Record<string, unknown>): string {
line += `${key}=${stringValue} `
}
- // trim trailing space
return line.substring(0, line.length - 1)
}
diff --git a/src/observability/logger/middleware/get-automatic-request-logger.ts b/src/observability/logger/middleware/get-automatic-request-logger.ts
index 946695ace75e..5cef1caecd88 100644
--- a/src/observability/logger/middleware/get-automatic-request-logger.ts
+++ b/src/observability/logger/middleware/get-automatic-request-logger.ts
@@ -44,7 +44,7 @@ export function getAutomaticRequestLogger() {
} else if (shouldEnableAutomaticDevLogging()) {
const logLevelNum = getLogLevelNumber()
- // Don't log `/_next/` requests unless LOG_LEVEL is `debug` or higher
+ // Suppress /_next/ requests unless LOG_LEVEL is debug or more verbose.
if (url?.startsWith('/_next/') && logLevelNum < 3) {
return originalEnd.apply(this, args as Parameters<typeof originalEnd>)
}
diff --git a/src/observability/middleware/handle-errors.ts b/src/observability/middleware/handle-errors.ts
index f43857cffdf1..e0b100026de2 100644
--- a/src/observability/middleware/handle-errors.ts
+++ b/src/observability/middleware/handle-errors.ts
@@ -44,6 +44,8 @@ async function logException(error: ErrorWithCode, req: ExtendedRequest) {
}
}
+// For asset 404s, handleError sets short cache headers because Fastly caches 404 responses.
+// https://docs.fastly.com/en/guides/how-caching-and-cdns-work#http-status-codes-cached-by-default
async function handleError(
error: ErrorWithCode | number,
req: ExtendedRequest,
@@ -54,14 +56,8 @@ async function handleError(
if (req.path.startsWith('/assets') || req.path.startsWith('/_next/static')) {
if (!responseDone) {
- // Fastly caches 404s by default, so cache 404'ing assets conservatively:
- // a short Cache-Control, plus the default surrogate key
- // in case the 404 was a mistake.
- // https://docs.fastly.com/en/guides/how-caching-and-cdns-work#http-status-codes-cached-by-default
errorCacheControl(res)
- // Unsets the manual surrogate key assumed earlier in the middleware chain.
- // Falls back to `no-language` when `req.language` isn't set yet,
- // e.g. errors before language detection.
+ // Clear any earlier manual surrogate key; pre-language errors fall back to no-language.
setFastlySurrogateKey(res, makeLanguageSurrogateKey(req.language), true)
}
} else if (DEBUG_MIDDLEWARE_TESTS) {
@@ -74,7 +70,7 @@ async function handleError(
await logException(error, req)
}
- // We MUST delegate to the default Express error handler
+ // Delegate once headers are sent or the request aborted, so Express closes the connection.
next(error)
return
}
@@ -83,7 +79,7 @@ async function handleError(
req.context = {}
}
- // Special handling for when a middleware calls `next(404)`
+ // Middleware may signal a normal 404 by calling next(404).
if (error === 404) {
errorCacheControl(res)
setFastlySurrogateKey(res, makeLanguageSurrogateKey(req.language), true)
@@ -94,29 +90,26 @@ async function handleError(
throw new Error("Don't use next(xxx) where xxx is any other number than 404")
}
- // display error on the page in development and staging, but not in production
+ // Development and staging pages show the error; production pages do not.
if (!process.env.MODA_PROD_SERVICE_ENV) {
req.context.error = error
}
- // Errors with a status code usually come from a middleware like `express.json()`.
+ // Status-code errors usually come from middleware such as express.json.
if (error.statusCode) {
res.sendStatus(error.statusCode)
return
}
res.statusCode = 500
- // Local dev doesn't need the pretty HTML rendering of 500.tsx.
- // Also, as of Jan 2024, calling nextApp.renderError hangs forever
- // when `NODE_ENV` is 'development'. We can't fully explain it,
- // and it's moot because in local dev the full stack trace is more useful.
+ // In development, nextApp.renderError hangs forever and the stack trace is more useful.
if (process.env.NODE_ENV === 'development') {
next(error)
return
} else {
nextApp.renderError(error, req, res, req.path)
- // Report to Failbot AFTER responding to the user
+ // Report to Failbot after responding to the user.
await logException(error, req)
}
} catch (handlingError) {
diff --git a/src/observability/middleware/trigger-error.ts b/src/observability/middleware/trigger-error.ts
index bcd1fee9157c..7009748fe058 100644
--- a/src/observability/middleware/trigger-error.ts
+++ b/src/observability/middleware/trigger-error.ts
@@ -2,19 +2,15 @@ import type { Response, NextFunction } from 'express'
import type { ExtendedRequest } from '@/types'
-// This module is for testing our handling of uncaught async rejections on incoming requests
+// Tests use this route to exercise uncaught async rejections on incoming requests.
-// IMPORTANT: Leave this function as `async` even though it doesn't need to be!
+// Keep triggerError async and unwrapped so it rejects like async middleware.
export default async function triggerError(
req: ExtendedRequest,
res: Response,
next: NextFunction,
) {
- // IMPORTANT:
- // Do NOT wrap this method's contents in the usual `try-catch+next(error)`
- // pattern used on async middleware! This is an intentional omission!
-
- // prevent this from being used in production
+ // Block intentional errors in production.
if (process.env.NODE_ENV === 'production' && process.env.MODA_PROD_SERVICE_ENV === 'true')
return next()
diff --git a/src/observability/tests/failbot.ts b/src/observability/tests/failbot.ts
index 4aef8b831345..2084a27abab7 100644
--- a/src/observability/tests/failbot.ts
+++ b/src/observability/tests/failbot.ts
@@ -34,14 +34,11 @@ describe('FailBot', () => {
process.env.HAYSTACK_URL = 'https://haystack.example.com'
const err = new Error('Kaboom')
const backendPromises = FailBot.report(err, { foo: 'bar' })
- // Production code doesn't need to await what `FailBot.report()` returns.
- // In vitest we await now,
- // so we can assert the POST requests happened.
+ // Tests await backend promises so assertions observe the POST request.
if (backendPromises) {
await Promise.all(await backendPromises)
}
- // What `.report()` returns doesn't matter, only that it POSTed.
expect(requestBodiesSent.length).toBe(1)
expect(requestBodiesSent[0]).toMatchObject({
diff --git a/src/observability/tests/get-automatic-request-logger.ts b/src/observability/tests/get-automatic-request-logger.ts
index 0151d35321d2..1204552d4591 100644
--- a/src/observability/tests/get-automatic-request-logger.ts
+++ b/src/observability/tests/get-automatic-request-logger.ts
@@ -176,7 +176,7 @@ describe('getAutomaticRequestLogger', () => {
await new Promise((resolve) => setTimeout(resolve, 20))
- expect(consoleLogs).toHaveLength(0) // Should be filtered out
+ expect(consoleLogs).toHaveLength(0)
})
it('should log _next requests when debug level is set', async () => {
@@ -244,7 +244,6 @@ describe('getAutomaticRequestLogger', () => {
expect(consoleLogs).toHaveLength(1)
const logOutput = consoleLogs[0]
- // Should include context fields (even if empty due to mocking)
expect(logOutput).toContain('requestUuid=')
expect(logOutput).toContain('path=')
})
@@ -259,7 +258,6 @@ describe('getAutomaticRequestLogger', () => {
})
it('should not log in test environment by default', async () => {
- // Explicit environment settings for CI stability.
vi.stubEnv('NODE_ENV', 'test')
vi.stubEnv('ENABLE_DEV_LOGGING', '')
vi.stubEnv('LOG_LIKE_PRODUCTION', '')
@@ -314,7 +312,7 @@ describe('getAutomaticRequestLogger', () => {
await new Promise((resolve) => setTimeout(resolve, 20))
expect(consoleLogs).toHaveLength(1)
- expect(consoleLogs[0]).toContain('-') // Should show '-' for missing content length
+ expect(consoleLogs[0]).toContain('-')
})
it('should handle missing status code', async () => {
@@ -327,7 +325,7 @@ describe('getAutomaticRequestLogger', () => {
await new Promise((resolve) => setTimeout(resolve, 20))
expect(consoleLogs).toHaveLength(1)
- expect(consoleLogs[0]).toContain('200') // Should default to 200
+ expect(consoleLogs[0]).toContain('200')
})
it('should prefer originalUrl over url', async () => {
@@ -351,7 +349,6 @@ describe('getAutomaticRequestLogger', () => {
const startTime = Date.now()
middleware(mockReq as Request, mockRes as Response, mockNext)
- // Simulate some processing time
await new Promise((resolve) => setTimeout(resolve, 50))
;(mockRes as MockResponseWithEnd).end()
await new Promise((resolve) => setTimeout(resolve, 20))
@@ -367,7 +364,6 @@ describe('getAutomaticRequestLogger', () => {
if (responseTimeMatch) {
const loggedTime = parseInt(responseTimeMatch[1], 10)
- // Should be reasonably close to actual duration (within 20ms tolerance)
expect(loggedTime).toBeGreaterThanOrEqual(40)
expect(loggedTime).toBeLessThanOrEqual(actualDuration + 20)
}
diff --git a/src/observability/tests/logger-integration.ts b/src/observability/tests/logger-integration.ts
index c602e7243d15..9071ee9f0d74 100644
--- a/src/observability/tests/logger-integration.ts
+++ b/src/observability/tests/logger-integration.ts
@@ -16,7 +16,6 @@ function expectDevLog(logs: string[], level: string, message: string): void {
expect(match, `Expected a log containing "${level}" and "${message}"`).toBeDefined()
}
-// Integration tests that use real dependencies without mocks
describe('logger integration tests', () => {
let originalConsoleLog: typeof console.log
let originalConsoleError: typeof console.error
@@ -50,7 +49,6 @@ describe('logger integration tests', () => {
describe('logger context integration', () => {
it('should use empty context when no async local storage is set', () => {
- // Set production mode to see the context in the output
vi.stubEnv('LOG_LIKE_PRODUCTION', 'true')
vi.stubEnv('NODE_ENV', 'development')
@@ -60,7 +58,6 @@ describe('logger integration tests', () => {
expect(consoleLogs).toHaveLength(1)
const logOutput = consoleLogs[0]
- // Real getLoggerContext returns empty strings for fields when no context is set
expect(logOutput).toContain('level=info')
expect(logOutput).toContain('message="Test without context"')
expect(logOutput).toContain('timestamp=')
@@ -68,7 +65,6 @@ describe('logger integration tests', () => {
})
it('should use context from async local storage when available', async () => {
- // Set production mode to see the context in the output
vi.stubEnv('LOG_LIKE_PRODUCTION', 'true')
vi.stubEnv('NODE_ENV', 'development')
@@ -88,12 +84,9 @@ describe('logger integration tests', () => {
const mockRes = {} as unknown as Response
- // Use a Promise to handle the async local storage execution
const result = await new Promise<void>((resolve, reject) => {
- // Create a next function that will execute our test logic within the async context
const mockNext = () => {
try {
- // Update the context with additional values (simulating subsequent middleware)
updateLoggerContext({
language: 'es',
userLanguage: 'es',
@@ -144,7 +137,7 @@ describe('logger integration tests', () => {
logger.warn('Warn message')
logger.error('Error message')
- // With 'info' level, debug should be filtered out (debug=3, info=2, so debug > info)
+ // LOG_LEVEL numbers increase with verbosity, so debug 3 is filtered by info 2.
const allClean = consoleLogs.map(stripAnsi).join('\n')
expect(allClean).not.toContain('Debug message')
expectDevLog(consoleLogs, 'INFO', 'Info message')
@@ -167,7 +160,7 @@ describe('logger integration tests', () => {
logger.warn('Warn message')
logger.error('Error message')
- // With 'error' level (0), only error should be logged
+ // error 0 filters every higher-verbosity level.
const allClean = consoleLogs.map(stripAnsi).join('\n')
expect(allClean).not.toContain('Debug message')
expect(allClean).not.toContain('Info message')
@@ -197,10 +190,10 @@ describe('logger integration tests', () => {
consoleLogs.length = 0
consoleErrors.length = 0
- // Test NODE_ENV=production (but not in CI)
+ // CI disables production logging unless LOG_LIKE_PRODUCTION is true.
vi.stubEnv('NODE_ENV', 'production')
- vi.stubEnv('CI', '') // Ensure CI is not set
- vi.stubEnv('LOG_LIKE_PRODUCTION', '') // Clear this to test production detection
+ vi.stubEnv('CI', '')
+ vi.stubEnv('LOG_LIKE_PRODUCTION', '')
const logger = createLogger('file:///path/to/test.js')
logger.info('Real production logging test')
diff --git a/src/observability/tests/logger.ts b/src/observability/tests/logger.ts
index 3b446c459575..69052a424bc6 100644
--- a/src/observability/tests/logger.ts
+++ b/src/observability/tests/logger.ts
@@ -1,7 +1,7 @@
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
import { createLogger } from '@/observability/logger'
-// Mock only the logger-context for most tests, but we'll test integration without mocks
+// Most tests mock logger context; integration coverage lives in logger-integration.ts.
vi.mock('@/observability/logger/lib/logger-context')
function stripAnsi(s: string): string {
@@ -212,11 +212,11 @@ describe('createLogger', () => {
logger.error('Multiple errors', error1, error2)
- // In development mode, each error triggers a separate console.log + console.error
+ // Development logging prints one console.log and one console.error per Error.
expect(consoleLogs).toHaveLength(2)
expect(consoleErrors).toHaveLength(2)
- // Both log entries should have the same message
+ // Both Error entries share the combined message.
expectDevLog(consoleLogs, 'ERROR', 'Multiple errors: First error, Second error')
expect(consoleErrors[0]).toBe(error1)
expect(consoleErrors[1]).toBe(error2)
@@ -430,7 +430,7 @@ describe('createLogger', () => {
vi.stubEnv('KUBE_NODE_HOSTNAME', 'ghe-k8s-node-42')
vi.stubEnv('LOG_LIKE_PRODUCTION', 'true')
- // Reset modules so pod-identity is re-evaluated with the new env vars
+ // Reset modules so pod-identity reads the stubbed environment.
vi.resetModules()
const { createLogger: freshCreateLogger } = await import('@/observability/logger')
@@ -530,7 +530,7 @@ describe('createLogger', () => {
const logOutput = consoleLogs[0]
expect(logOutput).toContain('included.error="Cannot read property"')
expect(logOutput).toContain('included.error_name=TypeError')
- // When .code is undefined, error_code is present but empty
+ // Undefined error.code serializes as an empty error_code field.
expect(logOutput).toMatch(/included\.error_code= /)
expect(logOutput).toContain('included.error_stack=')
})
diff --git a/src/observability/tests/to-error.ts b/src/observability/tests/to-error.ts
index 819621bd6428..71e88aa7dc84 100644
--- a/src/observability/tests/to-error.ts
+++ b/src/observability/tests/to-error.ts
@@ -38,8 +38,7 @@ describe('toError', () => {
it('should convert undefined to an Error via JSON.stringify', () => {
const result = toError(undefined)
expect(result).toBeInstanceOf(Error)
- // JSON.stringify(undefined) returns undefined (not a string),
- // so new Error(undefined) has an empty message
+ // JSON.stringify(undefined) makes new Error(undefined) use an empty message.
expect(result.message).toBe('')
})
@@ -54,7 +53,6 @@ describe('toError', () => {
circular.self = circular
const result = toError(circular)
expect(result).toBeInstanceOf(Error)
- // String() on an object returns '[object Object]'
expect(result.message).toBe('[object Object]')
})
})
diff --git a/src/observability/tests/to-logfmt.test.ts b/src/observability/tests/to-logfmt.test.ts
index c75ff6f08df2..0f39a3cfc200 100644
--- a/src/observability/tests/to-logfmt.test.ts
+++ b/src/observability/tests/to-logfmt.test.ts
@@ -208,7 +208,7 @@ describe('toLogfmt', () => {
const result = toLogfmt(obj)
expect(result).toContain('name=test')
- expect(result).toContain('self=[Circular]') // Our implementation marks circular refs
+ expect(result).toContain('self=[Circular]')
})
it('should handle Date objects', () => {
diff --git a/src/pages/_document.tsx b/src/pages/_document.tsx
index 311fc39c040b..92d962b3d572 100644
--- a/src/pages/_document.tsx
+++ b/src/pages/_document.tsx
@@ -3,23 +3,18 @@ import Document, { Html, Head, Main, NextScript } from 'next/document'
import { defaultCSSTheme } from '@/color-schemes/components/useTheme'
import { colorModeScript } from '@/color-schemes/lib/color-mode-script'
+// MyDocument leaves SSR theme attributes at defaultCSSTheme so the HTML stays shared-cacheable.
+// colorModeScript updates them from the color_mode cookie before the browser's first paint.
+// colorModeScript injects executable JS, not content HTML, so RenderedHTML and hast do not apply.
export default class MyDocument extends Document {
render() {
return (
<Html
- // These values are always the SSR rendering defaults.
- // Before the browser's first paint, the inline `colorModeScript`
- // below updates them on the client from the `color_mode` cookie, so
- // the page paints with the user's real theme and doesn't flash. The
- // SSR defaults stay constant, so the HTML remains shared-cacheable.
data-color-mode={defaultCSSTheme.colorMode}
data-light-theme={defaultCSSTheme.lightTheme}
data-dark-theme={defaultCSSTheme.darkTheme}
>
<Head>
- {/* Inline color-mode script must run before paint to avoid a flash; it
- injects executable JS (not content HTML), so RenderedHTML/hast do
- not apply here. */}
{/* eslint-disable-next-line custom-rules/no-dangerously-set-inner-html */}
<script dangerouslySetInnerHTML={{ __html: colorModeScript }} />
</Head>
diff --git a/src/pages/_error.tsx b/src/pages/_error.tsx
index 7beaf0d627bf..6f0624d72718 100644
--- a/src/pages/_error.tsx
+++ b/src/pages/_error.tsx
@@ -18,27 +18,24 @@ function Error() {
return <GenericError />
}
+// Importing @/observability/lib/failbot here would pull it into the client bundle.
+// renderPage middleware attaches FailBot to SSR requests.
+// Excluding it in next.config.ts complicates Next.js upgrades.
Error.getInitialProps = async (ctx: NextPageContext) => {
- // `.res` only exists during SSR,
- // so its presence is how we know to send this error to Failbot.
+ // ctx.res only exists during SSR, so it gates FailBot reporting.
const { err, req, res } = ctx
let statusCode = 500
if (res?.statusCode) {
statusCode = res.statusCode
}
- // `err` is falsy for a 404, which `pages/404.tsx` handles instead.
+ // Missing pages become 404 responses in render-page, so this only reports real errors.
if (err && res && req) {
- // We can't import `@/observability/lib/failbot` here,
- // because webpack pulls this file into the client bundle.
- // Excluding it in next.config.ts would work but makes future Next.js upgrades harder.
- // Instead the contextualizers attach FailBot to the Express request,
- // so it exists only in SSR.
const expressRequest = req as unknown as ExpressRequestExtensions
const FailBot = expressRequest.FailBot
if (FailBot) {
try {
- // Allowlist: these headers carry no PII.
+ // Report only the request headers listed in OK_HEADER_KEYS.
const OK_HEADER_KEYS = ['user-agent', 'referer', 'accept-encoding', 'accept-language']
const reported = FailBot.report(err, {
path: req.url || '',
@@ -60,8 +57,7 @@ Error.getInitialProps = async (ctx: NextPageContext) => {
),
})
- // `FailBot.report()` returns undefined when no backends are configured,
- // otherwise an array of promises.
+ // FailBot.report returns undefined without backends, or an array of promises.
if (!reported) {
console.warn(
'The FailBot.report() returned undefined which means the error was NOT sent to Failbot.',
@@ -71,8 +67,7 @@ Error.getInitialProps = async (ctx: NextPageContext) => {
reported.length &&
reported.every((thing) => thing instanceof Promise)
) {
- // Await even though we ignore the results.
- // Leaving these to the event loop produces cryptic errors when one rejects.
+ // Await ignored results so rejected reports do not surface later as unclear errors.
try {
await Promise.all(reported)
} catch (error) {
@@ -80,8 +75,7 @@ Error.getInitialProps = async (ctx: NextPageContext) => {
}
}
} catch (error) {
- // This catch exists so a FailBot problem can't stop the error page from rendering.
- // It doesn't mean the report failed to send.
+ // Keep FailBot problems from blocking rendering; the report may still have sent.
console.warn('Failed to send error to FailBot.', error)
}
}
diff --git a/src/products/lib/all-products.ts b/src/products/lib/all-products.ts
index fd7dd1035eaa..7bc174d5cc89 100644
--- a/src/products/lib/all-products.ts
+++ b/src/products/lib/all-products.ts
@@ -22,7 +22,7 @@ export interface ProductMap {
[productId: string]: Product
}
-// Both internal and external products are specified in content/index.md
+// content/index.md specifies both internal and external products.
const homepage = path.posix.join(ROOT, 'content/index.md')
export const { data } = frontmatter(fs.readFileSync(homepage, 'utf8'))
@@ -35,7 +35,7 @@ for (const productId of productIds) {
const relPath = productId
const dir = path.join(ROOT, 'content', relPath)
- // Early Access may not exist in the current checkout
+ // Early Access can be absent from the current checkout.
try {
fs.readdirSync(dir)
} catch {
diff --git a/src/products/lib/get-product-groups.ts b/src/products/lib/get-product-groups.ts
index eb62a7ee8e08..e5c24643a3bd 100644
--- a/src/products/lib/get-product-groups.ts
+++ b/src/products/lib/get-product-groups.ts
@@ -10,6 +10,9 @@ import languages from '@/languages/lib/languages-server'
type PageMap = Record<string, Page>
+// childGroups stores ids such as code-security/dependabot, not localized, versioned hrefs.
+// Try the localized current-version href first, then fall back to product.versions[0]
+// from productMap.
async function getPage(
id: string,
lang: string,
@@ -21,15 +24,6 @@ async function getPage(
const external = product.external || false
- // We only have an `id` like 'code-security/dependabot',
- // so the href has to be guessed.
- // On `/fr/enterprise-server@3.9` we try
- // `/fr/enterprise-server@3.9/code-security/dependabot` first.
- // Pages aren't available in every version,
- // so the fallback is `product.versions[0]` from the `productMap`,
- // not to be confused with the `pageMap`.
- // That keeps the current version when it applies,
- // and degrades to the first when it doesn't.
let href = product.href
let name = product.name
@@ -39,9 +33,6 @@ async function getPage(
if (!external) {
href = removeFPTFromPath(path.posix.join('/', lang, context.currentVersion, id))
if (!pageMap[href]) {
- // Fall back to `product.versions[0]`.
- // For example, you're on `/en/enterprise-server@3.1`
- // but `/foo/bar` only exists in `enterprise-cloud@latest`.
if (!product.versions) throw new Error(`Product ${productId} has no versions`)
href = removeFPTFromPath(path.posix.join('/', lang, product.versions[0], id))
}
@@ -52,8 +43,7 @@ async function getPage(
)
}
- // Some should not be included for the current version, and returning
- // undefined here means this entry will be filtered out by the caller.
+ // Returning undefined lets the caller filter products unavailable in the current version.
const isFPT = context.currentVersion === 'free-pro-team@latest'
if (!isFPT && !page.applicableVersions.includes(context.currentVersion)) {
return
@@ -65,16 +55,14 @@ async function getPage(
throwIfEmpty: false,
})
}
- // Either the page didn't have a `rawShortTitle` or it was empty when
- // rendered out with Liquid. Either way, have to fall back to `rawTitle`.
+ // Fall back to rawTitle when rawShortTitle is missing or Liquid renders it empty.
if (!name || !page.rawShortTitle) {
name = await renderContentWithFallback(page, 'rawTitle', context, {
textOnly: true,
})
}
}
- // Return only the props needed for the ProductSelectionCard, since
- // that's the only place this is ever used.
+ // ProductSelectionCard only needs these props.
return {
id,
name,
@@ -147,7 +135,7 @@ export async function getProductGroups(
lang: string,
context: Context,
): Promise<ProductGroup[]> {
- // Always use English version for structure (octicon, children)
+ // Use English childGroups for octicons and children; localized files supply names only.
const englishChildGroups = data?.childGroups || []
const localizedByOcticon = await getLocalizedGroupNames(lang)
@@ -160,7 +148,7 @@ export async function getProductGroups(
name: localizedName,
icon: group.icon || null,
octicon: group.octicon || null,
- // Typically the children are product IDs, but we support deeper page paths too
+ // Children are usually product IDs, but deeper page paths are also valid.
children: (
await Promise.all(group.children.map((id: string) => getPage(id, lang, pageMap, context)))
).filter(Boolean) as ProductGroupChild[],
diff --git a/src/products/tests/get-product-groups.ts b/src/products/tests/get-product-groups.ts
index 86630f7ca13a..49f15a53d13e 100644
--- a/src/products/tests/get-product-groups.ts
+++ b/src/products/tests/get-product-groups.ts
@@ -6,7 +6,7 @@ import {
getLocalizedGroupNames,
} from '@/products/lib/get-product-groups'
-// `name` is required here to match what the library expects.
+// name matches the helper's required ProductGroupData shape.
interface MockProductGroupData {
name: string
octicon?: string
@@ -67,7 +67,7 @@ describe('get-product-groups helper functions', () => {
const localizedByOcticon: { [key: string]: string } = {
RocketIcon: 'Empezar',
ShieldLockIcon: 'Seguridad',
- CopilotIcon: 'GitHub Copilot', // Some names stay the same
+ CopilotIcon: 'GitHub Copilot',
}
const nameMap: { [key: string]: string } = mapEnglishToLocalizedNames(
@@ -90,7 +90,7 @@ describe('get-product-groups helper functions', () => {
const localizedByOcticon: { [key: string]: string } = {
RocketIcon: 'Empezar',
- // MissingIcon is not in the localized map
+ // MissingIcon has no localized entry.
}
const nameMap: { [key: string]: string } = mapEnglishToLocalizedNames(
@@ -105,16 +105,16 @@ describe('get-product-groups helper functions', () => {
})
test('handles different ordering between English and localized groups', () => {
- // English groups in one order
+ // English groups use one order.
const englishGroups: MockProductGroupData[] = [
{ name: 'Get started', octicon: 'RocketIcon', children: [] },
{ name: 'Security', octicon: 'ShieldLockIcon', children: [] },
]
- // Localized groups in different order (but mapped by octicon)
+ // Localized groups use a different order and still map by octicon.
const localizedByOcticon: { [key: string]: string } = {
- ShieldLockIcon: 'Seguridad', // Security comes first in localized
- RocketIcon: 'Empezar', // Get started comes second
+ ShieldLockIcon: 'Seguridad',
+ RocketIcon: 'Empezar',
}
const nameMap: { [key: string]: string } = mapEnglishToLocalizedNames(
@@ -142,7 +142,7 @@ describe('get-product-groups helper functions', () => {
{ name: 'GitHub Copilot', octicon: 'CopilotIcon', children: ['copilot'] },
]
- // Simulate what would come from a Spanish localized file
+ // Spanish localized index data supplies translated names with matching octicons.
const mockLocalizedChildGroups: MockProductGroupData[] = [
{ name: 'Empezar', octicon: 'RocketIcon', children: ['get-started'] },
{ name: 'Seguridad', octicon: 'ShieldLockIcon', children: ['code-security'] },
@@ -170,7 +170,7 @@ describe('get-product-groups helper functions', () => {
expect(finalResult[1].name).toBe('Seguridad')
expect(finalResult[2].name).toBe('GitHub Copilot')
- // Technical data should remain unchanged
+ // Technical data remains unchanged.
expect(finalResult[0].octicon).toBe('RocketIcon')
expect(finalResult[0].children).toEqual(['get-started'])
})
diff --git a/src/redirects/lib/exception-redirects.ts b/src/redirects/lib/exception-redirects.ts
index 131c3e175f9f..8f26a20af657 100644
--- a/src/redirects/lib/exception-redirects.ts
+++ b/src/redirects/lib/exception-redirects.ts
@@ -2,9 +2,8 @@ import fs from 'fs'
type Redirects = Record<string, string>
-// Parses the exception redirects .txt format: a bare line is a destination, and
-// each following line starting with `-` is a source that redirects to it.
-// Lines starting with `#` are comments.
+// Exception redirect files use bare destinations followed by - source lines.
+// Lines starting with # are comments.
export default function getExceptionRedirects(exceptionsTxtFile: string): Redirects {
const exceptions: Redirects = {}
const exceptionRedirectsLines = fs
diff --git a/src/redirects/lib/get-redirect.ts b/src/redirects/lib/get-redirect.ts
index 502d37fd3631..07bca4cfff59 100644
--- a/src/redirects/lib/get-redirect.ts
+++ b/src/redirects/lib/get-redirect.ts
@@ -39,13 +39,10 @@ export default function getRedirect(uri: string, context: Context): string | und
const [language, withoutLanguage] = splitPathByLanguage(uri, userLanguage)
if (withoutLanguage.startsWith('/github-ae@latest')) {
- // It has a different business logic that the rest because it's a
- // version that now will always redirect. Just a question of where to
- // exactly.
+ // githubAERedirect maps GitHub AE URLs to a non-AE destination.
const nonAERedirect = githubAERedirect(uri, context)
if (nonAERedirect.includes('/github-ae@latest')) {
- // If this happened some redirect in there didn't completely
- // get away from github-ae.
+ // GitHub AE redirects must not point back to GitHub AE.
throw new Error('Still going to github-ae@latest URL')
}
return nonAERedirect
@@ -53,15 +50,9 @@ export default function getRedirect(uri: string, context: Context): string | und
let destination: string | undefined
- // `redirects` is sourced from more than one thing. The primary use
- // case is gathering up the `redirect_from` frontmatter key.
- // But we also have `developer.json` which contains legacy redirects.
- // For example, the `developer.json` will have entries such
- // `/enterprise/v4/enum/auditlogorderfield` which clearly is using
- // the old formatting of the version. So to leverage the redirects
- // from `developer.json` we'll look at it right away.
+ // Check redirects first because developer.json has /enterprise/v4/enum/auditlogorderfield.
if (withoutLanguage in redirects) {
- // But only inject the language if it's NOT an external redirect
+ // External redirects already include their full destination.
if (redirects[withoutLanguage].includes('://')) {
return redirects[withoutLanguage]
}
@@ -71,10 +62,10 @@ export default function getRedirect(uri: string, context: Context): string | und
let basicCorrection: string | undefined
if (withoutLanguage.startsWith(nonEnterpriseDefaultVersionPrefix)) {
- // E.g. '/free-pro-team@latest/foo/bar' or '/free-pro-team@latest'
+ // Example: /free-pro-team@latest/actions or /free-pro-team@latest
basicCorrection = `/${language}${withoutLanguage.replace(nonEnterpriseDefaultVersionPrefix, '')}`
} else if (withoutLanguage.replace('/', '') in allVersions && !languagePrefixRegex.test(uri)) {
- // E.g. just '/github-ae@latest' or '/enterprise-cloud@latest'
+ // Example: /enterprise-cloud@latest
basicCorrection = `/${language}${withoutLanguage}`
return basicCorrection
}
@@ -83,23 +74,22 @@ export default function getRedirect(uri: string, context: Context): string | und
withoutLanguage === '/enterprise-server' ||
withoutLanguage.startsWith('/enterprise-server/')
) {
- // E.g. '/enterprise-server' or '/enterprise-server/3.0/foo'
+ // Example: /enterprise-server or /enterprise-server/3.0/admin
basicCorrection = `/${language}${withoutLanguage.replace(
'/enterprise-server',
`/enterprise-server@${latestStable}`,
)}`
- // If it's now just the version, without anything after, exit here
+ // Version home pages need no redirect lookup.
if (withoutLanguage === '/enterprise-server') {
return basicCorrection
}
} else if (withoutLanguage.startsWith('/enterprise-server@latest')) {
- // E.g. '/enterprise-server@latest' or '/enterprise-server@latest/3.3/foo'
+ // Example: /enterprise-server@latest or /enterprise-server@latest/3.3/admin
basicCorrection = `/${language}${withoutLanguage.replace(
'/enterprise-server@latest',
`/enterprise-server@${latestStable}`,
)}`
- // If it was *just* '/enterprise-server@latest' all that's needed is
- // the language but with 'latest' replaced with the value of `latest`
+ // Version home pages need only the language and resolved latest version.
if (withoutLanguage === '/enterprise-server@latest') {
return basicCorrection
}
@@ -107,14 +97,10 @@ export default function getRedirect(uri: string, context: Context): string | und
withoutLanguage.startsWith('/enterprise/') &&
supportedAndRecentlyDeprecated.includes(withoutLanguage.split('/')[2])
) {
- // E.g. '/enterprise/3.3' or '/enterprise/3.3/foo' or '/enterprise/3.0/foo
-
- // If the URL is without a language, and no redirect is necessary,
- // but it has as version prefix, the language has to be there
- // otherwise it will never be found in `req.context.pages`
+ // Example: /enterprise/3.3/admin needs a language prefix for req.context.pages lookup.
const version = withoutLanguage.split('/')[2]
if (withoutLanguage === `/enterprise/${version}`) {
- // E.g. `/enterprise/3.0`
+ // Example: /enterprise/3.0
basicCorrection = `/${language}${withoutLanguage.replace(
`/enterprise/${version}`,
`/enterprise-server@${version}`,
@@ -127,22 +113,19 @@ export default function getRedirect(uri: string, context: Context): string | und
)}`
}
} else if (withoutLanguage === '/enterprise') {
- // E.g. `/enterprise` exactly
+ // Example: /enterprise
basicCorrection = `/${language}/enterprise-server@${latest}`
return basicCorrection
} else if (
withoutLanguage.startsWith('/enterprise/') &&
!supported.includes(withoutLanguage.split('/')[2])
) {
- // E.g. '/en/enterprise/user/github/foo'
- // If the URL is without a language, and no redirect is necessary,
- // but it has as version prefix, the language has to be there
- // otherwise it will never be found in `req.context.pages`
+ // Example after language removal: /enterprise/user/github/actions needs a language prefix.
basicCorrection = `/${language}${withoutLanguage
.replace(`/enterprise/`, `/enterprise-server@${latest}/`)
.replace('/user/', '/')}`
} else if (withoutLanguage.startsWith('/insights')) {
- // E.g. '/insights/foo'
+ // Example: /insights/admin
basicCorrection = uri.replace('/insights', `${language}/enterprise-server@${latest}/insights`)
}
@@ -162,7 +145,7 @@ export default function getRedirect(uri: string, context: Context): string | und
withoutLanguage.split('/')[1].includes('@') &&
withoutLanguage.split('/')[1] in allVersions
) {
- // E.g. '/enterprise-server@latest' or '/github-ae@latest' or '/enterprise-server@3.3'
+ // The first segment is a known version, such as /enterprise-server@3.XX.
const majorVersion = withoutLanguage.split('/')[1].split('@')[0]
const split = withoutLanguage.split('/')
const version = split[1].split('@')[1]
@@ -181,20 +164,20 @@ export default function getRedirect(uri: string, context: Context): string | und
suffix = tryReplacements(prefix, suffix, context) || suffix
}
} else {
- // If version is not supported, we still need to set these values
+ // Unsupported versions still need prefix and suffix values for the fallback lookup.
prefix = `/${majorVersion}@${version}`
suffix = `/${split.slice(2).join('/')}`
}
const newURL = prefix + suffix
if (newURL !== withoutLanguage) {
- // At least the prefix changed!
+ // Prefix changes can target either a redirect or a live URL.
destination = redirects[newURL] || newURL
} else {
destination = redirects[newURL]
}
} else if (withoutLanguage.startsWith('/desktop/guides/')) {
- // E.g. /desktop/guides/contributing-and-collaborat
+ // Example: /desktop/guides/contributing-and-collaboration
const newURL = withoutLanguage.replace('/desktop/guides/', '/desktop/')
destination = redirects[newURL] || newURL
} else {
@@ -202,8 +185,7 @@ export default function getRedirect(uri: string, context: Context): string | und
}
if (destination !== undefined) {
- // There's hope! Now we just need to attach the correct language
- // to the destination URL.
+ // Redirect destinations need the resolved language prefix.
return `/${language}${destination}`
}
@@ -214,31 +196,26 @@ function githubAERedirect(uri: string, context: Context): string {
const { redirects, userLanguage, pages } = context
if (!redirects || !pages) {
- // Fallback to home page if context is incomplete
+ // Incomplete context cannot choose an equivalent GitHub AE page.
const [language] = splitPathByLanguage(uri, userLanguage)
return `/${language}`
}
const [language, withoutLanguage] = splitPathByLanguage(uri, userLanguage)
- // From now on, github-ae@latest redirects to enterprise-cloud or
- // fpt or the home page.
+ // Try Enterprise Cloud and Free/Pro/Team equivalents before redirect and home-page fallbacks.
const cloudEquivalent = uri.replace('/github-ae@latest', '/enterprise-cloud@latest')
const fptEquivalent = uri.replace('/github-ae@latest', '')
const withoutVersion = withoutLanguage.replace('/github-ae@latest', '')
if (!withoutVersion) {
- // That means the version home page.
- // Don't even need to check if that exists.
- // But if it was without language, inject the language as
- // we go to the enterprise-cloud equivalent
+ // GitHub AE home redirects to Enterprise Cloud without checking pages.
if (uri.startsWith('/github-ae@latest')) {
return `/${language}${cloudEquivalent}`
}
return cloudEquivalent
}
- // What if the only missing thing is a language prefix, then
- // it's easy too.
+ // Language-less GitHub AE URLs can still match a translated equivalent.
if (uri.startsWith('/github-ae@latest')) {
const languageCloudEquivalent = `/${language}${cloudEquivalent}`
if (languageCloudEquivalent in pages) {
@@ -250,7 +227,7 @@ function githubAERedirect(uri: string, context: Context): string {
return languageFptEquivalent
}
} else {
- // If you're here it means the URL did start with a language.
+ // Language-prefixed GitHub AE URLs can check equivalent pages directly.
if (cloudEquivalent in pages) {
return cloudEquivalent
}
@@ -259,8 +236,7 @@ function githubAERedirect(uri: string, context: Context): string {
}
}
- // There are redirect exceptions the specifically spell out github-ae
- // in the redirect.
+ // Exception redirects can point GitHub AE URLs to a non-AE destination.
const legacyRedirect = redirects[withoutLanguage]
if (legacyRedirect && !legacyRedirect.includes('/github-ae@latest')) {
if (legacyRedirect.includes('://')) {
@@ -269,9 +245,7 @@ function githubAERedirect(uri: string, context: Context): string {
return `/${language}${legacyRedirect}`
}
- // The `redirects` are "pure" and don't specific a specific version.
- // For example `/articles/stuff` to `/get-started/new/name`
- // We look for those and try enterprise-cloud in it.
+ // Versionless redirects can still land on Enterprise Cloud or Free/Pro/Team equivalents.
if (redirects[withoutVersion]) {
const cloudCandidate = `/${language}/enterprise-cloud@latest${redirects[withoutVersion]}`
if (cloudCandidate in pages) {
@@ -279,8 +253,7 @@ function githubAERedirect(uri: string, context: Context): string {
}
const fptCandidate = `/${language}${redirects[withoutVersion]}`
- // The lookup of redirects might yield a versioned URL, whose version
- // might be github-ae or enterprise-server. Skip those.
+ // GitHub AE and Enterprise Server candidates would keep the reader on the wrong version.
if (fptCandidate in pages) {
const versionFromCandidate = getVersionStringFromPath(fptCandidate)
if (
@@ -294,16 +267,11 @@ function githubAERedirect(uri: string, context: Context): string {
}
}
- // Note that this includes completely unknown pages
+ // Unknown GitHub AE pages fall back to the localized home page.
return `/${language}`
}
-// Over time, we've developed multiple ambiguous patterns of URLs
-// You can't simply assume that all `/admin/guides` should become
-// `/admin` for example.
-// This function tries different string replacement on the suffix
-// (the pathname after the language and version part) until it
-// finds one string replacement that yields either a page or a redirect.
+// Ambiguous suffixes like /admin/guides need the first replacement that hits a page or redirect.
function tryReplacements(prefix: string, suffix: string, context: Context): string | undefined {
const { pages, redirects } = context
@@ -312,9 +280,7 @@ function tryReplacements(prefix: string, suffix: string, context: Context): stri
}
const test = (testSuffix: string): boolean => {
- // This is a generally broad search and replace and this particular
- // replacement has never been present in api documentation only enterprise
- // admin documentation, so we're excluding the REST api pages
+ // REST API paths are outside the Enterprise Admin replacement patterns.
if (testSuffix.includes('/rest')) {
return false
}
diff --git a/src/redirects/lib/graphql-category-redirect.ts b/src/redirects/lib/graphql-category-redirect.ts
index b31e1365766b..cd31f5578685 100644
--- a/src/redirects/lib/graphql-category-redirect.ts
+++ b/src/redirects/lib/graphql-category-redirect.ts
@@ -1,12 +1,8 @@
-// Dynamic redirect from legacy kind-based GraphQL reference URLs
-// (e.g. `/graphql/reference/scalars#boolean`) to the per-category
-// reference URLs (e.g. `/graphql/reference/other#scalar-boolean`)
-// introduced when docs-internal adopted the upstream `@docsCategory`
-// directive.
+// Redirect legacy kind-based GraphQL reference URLs, such as
+// /graphql/reference/scalars#boolean, to per-category reference URLs, such as
+// /graphql/reference/other#scalar-boolean.
//
-// Resolved in a single hop so the type-name (in the URL fragment) is not
-// lost: fragments are not sent on subsequent requests, so we can't chain a
-// /v4 redirect to a removed kind page and recover the type later.
+// Resolve in one hop because URL fragments are not sent on subsequent requests.
import fs from 'fs'
import path from 'path'
@@ -21,15 +17,15 @@ import {
} from '@/graphql/lib/categories'
import { supported as supportedGhes } from '@/versions/lib/enterprise-server-releases'
-// URL kind segment (e.g. "input-objects") -> internal kind key (e.g. "inputObjects").
+// URL kind segment input-objects maps to internal kind key inputObjects.
const URL_TO_KIND_KEY: Record<string, SchemaKindKey> = Object.fromEntries(
ALL_KIND_KEYS.map((k) => [KIND_URL_SEGMENT[k], k]),
)
-// Set of legacy kind URL segments we redirect from.
+// Accept only these legacy kind segments for redirect parsing.
const LEGACY_KIND_SEGMENTS = new Set(Object.keys(URL_TO_KIND_KEY))
-// Per-version lookup: kind key -> id (lowercased) -> category slug.
+// Per-version lookup maps kind key to lowercased ID to category slug.
type CategoryMap = Partial<Record<SchemaKindKey, Record<string, string>>>
const dataDir = path.join(process.cwd(), 'src/graphql/data')
@@ -48,42 +44,36 @@ function loadCategoryMap(version: string): CategoryMap | null {
return map
}
-// Map URL version segment to a graphql data directory name. Returns null for
-// unsupported / archived versions so the caller can pass them through.
+// Unsupported and archived versions pass through because they have no GraphQL data directory.
function versionUrlToDataDir(versionSegment: string | null): string | null {
if (!versionSegment || versionSegment === 'free-pro-team@latest') return 'fpt'
if (versionSegment === 'enterprise-cloud@latest') return 'ghec'
const m = /^enterprise-server@(\d+\.\d+)$/.exec(versionSegment)
if (m && supportedGhes.includes(m[1])) return `ghes-${m[1]}`
- // enterprise-server@latest also has category data via its current alias,
- // but middleware order means we shouldn't see it here. Pass through.
+ // enterprise-server@latest has category data, but earlier middleware resolves it.
return null
}
const LANGUAGE_RE = new RegExp(`^(${languageKeys.join('|')})$`)
const VERSION_RE = /^(free-pro-team@latest|enterprise-cloud@latest|enterprise-server@[\d.]+)$/
-// Parse a docs URL path into its segments. Returns null if the path is not a
-// graphql-reference legacy kind URL.
+// Parse only legacy GraphQL reference kind URLs.
interface ParsedLegacyUrl {
language: string | null
version: string | null
kindSegment: string
- // Type id (lowercased) parsed from the URL fragment, if any.
+ // Lowercased type ID from the URL fragment, if any.
typeId: string | null
}
function parseLegacyUrl(input: string): ParsedLegacyUrl | null {
- // We accept `redirect` strings that may include a `#fragment` but should not
- // include a query string at this point (callers pass the path-only form).
+ // Callers pass path-only redirects, with optional fragments but no query strings.
const hashIndex = input.indexOf('#')
const pathPart = hashIndex >= 0 ? input.slice(0, hashIndex) : input
const fragment = hashIndex >= 0 ? input.slice(hashIndex + 1) : ''
const segments = pathPart.split('/').filter(Boolean)
- // Expect segments to look like:
- // [<lang>?, <version>?, "graphql", "reference", "<kind>"]
- // with optional language and optional version.
+ // The legacy shape allows optional language and version segments before graphql/reference/kind.
const refIdx = segments.indexOf('reference')
if (refIdx < 0) return null
if (segments[refIdx - 1] !== 'graphql') return null
@@ -92,7 +82,7 @@ function parseLegacyUrl(input: string): ParsedLegacyUrl | null {
const kindSegment = segments[refIdx + 1]
if (!LEGACY_KIND_SEGMENTS.has(kindSegment)) return null
- // The bits before "graphql" can be: nothing, [lang], [version], or [lang, version].
+ // Segments before graphql can be empty, language, version, or language plus version.
const preface = segments.slice(0, refIdx - 1)
let language: string | null = null
let version: string | null = null
@@ -118,13 +108,9 @@ function buildPrefix(language: string | null, version: string | null): string {
return out
}
-// Resolve a legacy URL to its category-based equivalent. Returns null if the
-// input is not a legacy URL or its version is not supported (so callers leave
-// it alone).
+// Resolve legacy type URLs to category pages and bare kind URLs to the reference root.
//
-// `fallbackLanguage` is used when the input URL has no language segment so the
-// rewritten URL is still valid against the language-prefixed `req.context.pages`
-// lookup downstream.
+// fallbackLanguage keeps language-less inputs valid against req.context.pages.
export function applyGraphqlCategoryRedirect(
redirect: string,
fallbackLanguage: string = 'en',
@@ -138,8 +124,7 @@ export function applyGraphqlCategoryRedirect(
const language = parsed.language ?? fallbackLanguage
const prefix = buildPrefix(language, parsed.version)
- // No fragment: legacy bare kind page (e.g. /graphql/reference/scalars). The
- // kind index doesn't exist anymore; send the user to the reference root.
+ // Legacy bare kind pages like /graphql/reference/scalars redirect to the reference root.
if (!parsed.typeId) {
return `${prefix}/graphql/reference`
}
@@ -152,8 +137,7 @@ export function applyGraphqlCategoryRedirect(
return `${prefix}/graphql/reference/${category}#${slugPrefix}-${parsed.typeId}`
}
-// Test-only helper to reset the per-version cache so unit tests can reload
-// fixture maps. Not exported through the public barrel.
+// Tests reset the per-version cache to reload fixture maps without exporting through the barrel.
export function __resetGraphqlCategoryCacheForTests(): void {
lookupCache.clear()
}
diff --git a/src/redirects/lib/permalinks.ts b/src/redirects/lib/permalinks.ts
index 6974dce431b4..00946ac6440e 100644
--- a/src/redirects/lib/permalinks.ts
+++ b/src/redirects/lib/permalinks.ts
@@ -5,6 +5,10 @@ import type { Permalink } from '@/types'
type Redirects = Record<string, string>
+// Versionless redirect fallbacks use the first supported version in lib/all-versions.ts order.
+// Input: /billing/managing-billing-for-your-github-account/managing-invoices-for-your-enterprise
+// Output:
+// /enterprise-cloud@latest/billing/managing-billing-for-your-github-account/managing-invoices-for-your-enterprise
export default function permalinkRedirects(
permalinks: Permalink[],
redirectFrom: string[],
@@ -12,19 +16,12 @@ export default function permalinkRedirects(
const redirects: Redirects = {}
if (!permalinks.length) return redirects
- // The following is handling for versionless redirect fallbacks!
- // We put an entry into `redirects` without any version prefix that goes to the first supported
- // version in the lib/all-versions.ts order. For example, we want this versionless path:
- // /billing/managing-billing-for-your-github-account/managing-invoices-for-your-enterprise
- // to redirect to its first supported version, which is GHEC:
- // /enterprise-cloud@latest/billing/managing-billing-for-your-github-account/managing-invoices-for-your-enterprise
if (permalinks[0].pageVersion !== nonEnterpriseDefaultVersion) {
redirects[getPathWithoutVersion(permalinks[0].hrefWithoutLanguage)] =
permalinks[0].hrefWithoutLanguage
}
- // For every "old" path in a content file's redirect_from frontmatter, also add that path to
- // the redirects object as a key, where the value is the content file's permalink.
+ // redirect_from entries need both versionless and version-prefixed redirect keys.
for (let frontmatterOldPath of redirectFrom) {
if (!frontmatterOldPath.startsWith('/')) {
throw new Error(
@@ -32,23 +29,18 @@ export default function permalinkRedirects(
)
}
- // Exceptions where the `redirect_from` entries are too old
- // Only replace /enterprise/ when it's at the start of the path followed by /admin/
- // This handles legacy patterns like /enterprise/admin/... → /admin/...
- // but preserves paths like /early-access/enterprise/... where enterprise is a directory name
+ // Collapse /admin/guides/ and leading /enterprise/admin/, but preserve nested /enterprise/.
frontmatterOldPath = frontmatterOldPath
.replace('/admin/guides/', '/admin/')
.replace(/^\/enterprise\/admin\//, '/admin/')
for (let index = 0; index < permalinks.length; index++) {
const permalink = permalinks[index]
- // For the first supported permalink (the order is determined by lib/all-versions),
- // put an entry into `redirects` without any version prefix.
+ // Versionless frontmatter redirects use the first supported permalink.
if (index === 0) {
redirects[frontmatterOldPath] = permalink.hrefWithoutLanguage
}
- // For every permalink, put an entry into `redirects` with the version prefix.
redirects[`/${permalink.pageVersion}${frontmatterOldPath}`] = permalink.hrefWithoutLanguage
}
}
diff --git a/src/redirects/lib/precompile.ts b/src/redirects/lib/precompile.ts
index ccd055b194a1..3c74615a4bd9 100644
--- a/src/redirects/lib/precompile.ts
+++ b/src/redirects/lib/precompile.ts
@@ -8,8 +8,7 @@ const EXCEPTIONS_FILE = './src/redirects/lib/static/redirect-exceptions.txt'
type Redirects = Record<string, string>
-// This function runs at server warmup and precompiles possible redirect routes.
-// It outputs them in key-value pairs within a neat JavaScript object: { oldPath: newPath }
+// Server warmup precompiles redirect routes as oldPath to newPath pairs.
export async function precompileRedirects(pageList: Page[]): Promise<Redirects> {
const allRedirects = readCompressedJsonFileFallback(
'./src/redirects/lib/static/developer.json',
@@ -20,47 +19,25 @@ export async function precompileRedirects(pageList: Page[]): Promise<Redirects>
) as Redirects
Object.assign(allRedirects, externalRedirects)
- // create backwards-compatible old paths for page permalinks and frontmatter redirects
+ // Page permalinks and frontmatter redirects need backward-compatible paths.
for (const page of pageList.filter((xpage) => xpage.languageCode === 'en')) {
Object.assign(allRedirects, page.buildRedirects())
}
- // Remove any redirect whose source URL is also a real page permalink.
- // This prevents redirect_from entries from clobbering live pages when a
- // new page (versioned broadly) declares a redirect_from that overlaps
- // with an older page that still exists in some versions.
+ // Live page permalinks win over redirect_from entries that overlap older page versions.
for (const page of pageList.filter((xpage) => xpage.languageCode === 'en')) {
for (const permalink of page.permalinks) {
delete allRedirects[permalink.hrefWithoutLanguage]
}
}
- // NOTE: Exception redirects **MUST COME AFTER** pageList redirects above in order
- // to properly override them. Exception redirects are unicorn one-offs that are not
- // otherwise handled by the versionless redirect fallbacks (see lib/all-versions.ts).
- //
- // Examples of exceptions:
- // * We deprecate the FPT version of a page, and we want the FPT version to redirect
- // to a different version that goes against the order in lib/all-versions.ts.
- // * We deprecate a non-FPT version of a page, and we want the old version to redirect
- // to a different version. Because the order in lib/all-versions.ts only covers
- // versionless links (like `/foo`), we need to specify an exception for the old
- // versioned links (like `/enterprise-cloud@latest/foo`).
- // * We deprecate a version of a page, and instead of falling back to the next
- // available version, we want to redirect that version to a different page entirely.
- //
- // The advantage of the exception redirects file is that it's encoded in plain
- // text so it's possible to write comments and it's also possible to write 1
- // destination URL once for each N redirect origins.
+ // The plain text format keeps one destination URL next to its many redirect origins.
const exceptions = getExceptionRedirects(EXCEPTIONS_FILE) as Redirects
+ // Apply exceptions last so versioned paths override fallback order or target another page.
Object.assign(allRedirects, exceptions)
for (const [fromURI, toURI] of Object.entries(allRedirects)) {
- // If the destination URL has a hardcoded `enterprise-server@latest` in
- // it we need to rewrite that now.
- // We never want to redirect to that as the final URL (in the 301 response)
- // but it might make sense for it to be in the `developer.json`
- // file since that is static.
+ // Static redirects can name enterprise-server@latest, but 301 responses need a real version.
if (toURI.includes('/enterprise-server@latest')) {
allRedirects[fromURI] = toURI.replace(
'/enterprise-server@latest',
diff --git a/src/redirects/lib/version-preference.ts b/src/redirects/lib/version-preference.ts
index 8227879fabd2..c6f089ba1a79 100644
--- a/src/redirects/lib/version-preference.ts
+++ b/src/redirects/lib/version-preference.ts
@@ -2,25 +2,20 @@ import { allVersions, allVersionKeys } from '@/versions/lib/all-versions'
import nonEnterpriseDefaultVersion from '@/versions/lib/non-enterprise-default-version'
import { getPathWithoutLanguage } from '@/frame/lib/path-utils'
-// Every version the reader can actually prefer over the unversioned form.
-// `detect-version.ts` already refuses cookie values outside `allVersionKeys`,
-// so anything reaching here is a real version.
+// detect-version.ts rejects cookie values outside allVersionKeys.
const alternateVersions = allVersionKeys.filter((v) => v !== nonEnterpriseDefaultVersion)
-// Segments that name a version rather than a product, in any form we have ever
-// served. `allVersions` is not enough on its own: it has no key for
-// `enterprise-server@latest`, for deprecated releases like `enterprise-server@3.0`,
-// or for the older `/enterprise/3.3/` and `/enterprise-server/3.9/` shapes. Those
-// still have to count as an explicit request, because a URL naming a version must
-// beat the cookie even when we no longer publish that version.
+// Explicit version URLs must beat the cookie. allVersions omits enterprise-server@latest,
+// deprecated releases like enterprise-server@3.0, and legacy shapes like /enterprise/3.3/
+// and /enterprise-server/3.9/.
const VERSION_PLANS = new Set([
...Object.values(allVersions).map((v) => v.plan),
'github-ae',
'enterprise',
])
-// Does this path name a version itself, rather than leaving it implied?
-// Anything with an `@` is a version segment, because no article slug contains one.
+// A path naming a version beats the cookie.
+// Anything with @ is a version segment, because article slugs do not contain it.
// The plan names cover the legacy unsuffixed shapes.
export function pathNamesAVersion(path: string): boolean {
const firstSegment = getPathWithoutLanguage(path).split('/')[1]
@@ -29,32 +24,23 @@ export function pathNamesAVersion(path: string): boolean {
}
export type VersionPreference = {
- // True when some version cookie value would have changed the response, so the
- // response has to vary on `x-user-version` even when this particular reader has
- // no cookie. Varying only for cookie holders would let a no-cookie reader's
- // cached page be served to someone who should have been redirected.
+ // True when any cookie could change the response, even when this reader has none.
+ // Without this Vary, caches can serve a no-cookie response to a reader who needs a redirect.
vary: boolean
- // Where to send this reader, if their preference applies and the article exists there.
+ // Preference destination, when the article exists there.
redirectTo?: string
}
const NOTHING: VersionPreference = { vary: false }
-// Work out whether a reader's version preference applies to a request.
+// A version cookie behaves like language: it is only the default.
//
-// The rule, decided in github/technical-content#7227, is that version behaves exactly
-// like language: the cookie is only a default, a version named in the URL always wins,
-// and an article that does not exist in the preferred version silently stays put.
+// A version named in the URL wins, and missing preferred-version articles stay put.
//
-// `requestPath` is the URL as asked for, and is what decides whether a version was
-// named. It has to be, because `getRedirect` strips an explicit `/free-pro-team@latest`
-// prefix before we get here. Reading the resolved path instead would make an explicit
-// request for Free/Pro/Team indistinguishable from no request at all, and a reader who
-// has set a cookie could never deliberately look at the Free/Pro/Team article again.
+// requestPath decides whether the URL named a version because getRedirect strips an
+// explicit /free-pro-team@latest prefix before this point.
//
-// `resolvedPath` is where the ordinary redirect logic decided to send them, and is what
-// the versioned candidate is built from, so a renamed article resolves in one hop
-// instead of two.
+// resolvedPath builds the versioned candidate so renamed articles resolve in one hop.
export function getVersionPreference(
requestPath: string,
resolvedPath: string,
@@ -66,15 +52,11 @@ export function getVersionPreference(
if (pathNamesAVersion(requestPath) || pathNamesAVersion(resolvedPath)) return NOTHING
- // Always a `URL.pathname` from the caller, so it always starts with `/` and this is
- // always the first segment. On a path that never got a language prefix this reads some
- // article slug as the language, and the candidate lookup below simply misses, because
- // every key in `pages` is language-prefixed.
+ // Language-less paths read a slug as the language and miss the language-prefixed pages lookup.
const language = resolvedPath.split('/')[1]
const withoutLanguage = getPathWithoutLanguage(resolvedPath)
- // `pages` is keyed by permalink, which carries no `.md` extension. Keep the extension
- // aside so a `.md` request redirects to the `.md` form of the versioned article.
+ // pages keys omit .md, but .md requests must redirect to .md versioned articles.
const extension = withoutLanguage.endsWith('.md') ? '.md' : ''
const lookupSuffix = extension ? withoutLanguage.slice(0, -extension.length) : withoutLanguage
@@ -83,8 +65,7 @@ export function getVersionPreference(
for (const version of alternateVersions) {
if (!(`/${language}/${version}${lookupSuffix}` in pages)) continue
- // At least one version of this article exists that the cookie could select, so the
- // response depends on the cookie whether or not this reader has one.
+ // Any selectable version makes the response depend on x-user-version.
vary = true
if (version === userVersion) {
redirectTo = `/${language}/${version}${lookupSuffix}${extension}`
diff --git a/src/redirects/middleware/handle-redirects.ts b/src/redirects/middleware/handle-redirects.ts
index d1e0d0d58427..0b25be9fb03c 100644
--- a/src/redirects/middleware/handle-redirects.ts
+++ b/src/redirects/middleware/handle-redirects.ts
@@ -13,21 +13,26 @@ import {
} from '@/frame/middleware/cache-control'
import { ExtendedRequest, URLSearchParamsTypes } from '@/types'
+// Version preference redirects stay in their own branch so cookie-dependent paths use 302.
+// A 301 would cache one reader's version preference in the browser.
+// Deep links from search, the product UI, or bookmarks otherwise ignore the cookie and serve
+// Free/Pro/Team. Measured corrective switching showed 1,288 moves to Enterprise Cloud and 500
+// moves to Enterprise Server per 24 hours.
+// When getVersionPreference returns vary without redirectTo, append Vary: x-user-version,
+// because the 200 response depends on the cookie.
+// Use append, not set, to keep existing Vary values.
+// src/versions/tests/version-cookie.ts verifies the served header.
export default function handleRedirects(req: ExtendedRequest, res: Response, next: NextFunction) {
if (!req.context) throw new Error('Request not contextualized')
- // Any double-slashes in the URL should be removed first
- // This must be done before checking if the path
- // is an asset (patterns.assetPaths)
+ // Collapse duplicate slashes before patterns.assetPaths, so //example.com cannot bypass handling.
if (req.path.includes('//')) {
return res.safeRedirect(301, req.path.replace(/\/+/g, '/'))
}
- // never redirect assets
if (patterns.assetPaths.test(req.path)) return next()
- // All /api/ endpoints handle their own redirects
- // such as /api/pageinfo redirects to /api/pageinfo/v1
+ // API endpoints handle their own redirects.
if (req.path.startsWith('/api/')) return next()
if (req.path === '/') {
@@ -50,12 +55,7 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
let redirect = req.path
let queryParams = req.originalUrl.includes('?') ? req.originalUrl.split('?')[1] : null
- // Redirect `/some/uri?q=stuff` to `/en/search?query=stuff`
- // Redirect `/some/uri?query=stuff` to `/en/search?query=stuff`
- // Redirect `/fr/version@latest/some/uri?query=stuff`
- // to `/fr/version@latest/search?query=stuff`
- // The `q` param is deprecated, but we still need to support it in case
- // there are links out there that use it.
+ // Route page searches to the search endpoint, and rename legacy q to query.
const onSearch = req.path.endsWith('/search') || req.path.startsWith('/api/search')
const hasQ = 'q' in req.query
const hasQuery = 'query' in req.query
@@ -71,9 +71,7 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
const { currentVersion } = req.context
if (currentVersion !== 'free-pro-team@latest') {
redirectTo += `/${currentVersion}`
- // The `req.context.currentVersion` is just the portion of the URL
- // pathname. It could be that the currentVersion is something
- // like `enterprise` which needs to be redirected to its new name.
+ // currentVersion comes from the path, so legacy names such as enterprise need getRedirect.
redirectTo = getRedirect(redirectTo, req.context) || redirectTo
}
@@ -81,21 +79,18 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
return res.safeRedirect(301, redirectTo)
}
- // have to do this now because searchPath replacement changes the path as well as the query params
if (queryParams) {
queryParams = `?${queryParams}`
}
- // remove query params temporarily so we can find the path in the redirects object
+ // Redirect keys omit query strings.
let redirectWithoutQueryParams = removeQueryParams(redirect)
const redirectTo = getRedirect(redirectWithoutQueryParams, req.context)
redirectWithoutQueryParams = redirectTo || redirectWithoutQueryParams
- // Resolve legacy `/graphql/reference/<kind>(#<name>)?` URLs to their
- // per-category equivalent. Done before query-param re-application so the
- // fragment parsing in the helper is unambiguous.
+ // Parse legacy GraphQL fragments before reapplying query params, so fragment parsing stays clear.
const graphqlRewrite = applyGraphqlCategoryRedirect(
redirectWithoutQueryParams,
req.context.userLanguage || 'en',
@@ -107,16 +102,9 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
redirect = queryParams ? redirectWithoutQueryParams + queryParams : redirectWithoutQueryParams
if (!redirectTo && !pathLanguagePrefixed(req.path)) {
- // No redirect necessary, but perhaps it's to a known page, and the URL
- // currently doesn't have a language prefix, then we need to add
- // the language prefix.
- // We can't always force on the language prefix because some URLs
- // aren't pages. They're other middleware endpoints such as
- // `/healthcheck` which should never redirect.
- // But for example, a `/authentication/connecting-to-github-with-ssh`
- // needs to become `/en/authentication/connecting-to-github-with-ssh`
+ // Add a language prefix only for pages or deprecated versions; /healthcheck passes through.
const possibleRedirectTo = `/en${req.path}`
- // Pages are keyed without .md, so strip it before lookup
+ // Pages are keyed without .md, so strip the extension before lookup.
const lookupPath = possibleRedirectTo.endsWith('.md')
? possibleRedirectTo.replace(/\.md$/, '')
: possibleRedirectTo
@@ -124,25 +112,13 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
if (lookupPath in req.context.pages || isDeprecatedVersion(req.path)) {
const language = getLanguage(req)
- // Note, it's important to use `req.url` here and not `req.path`
- // because the full URL can contain query strings.
- // E.g. `/foo?json=breadcrumbs`
+ // Use req.url here so redirects preserve query strings such as ?json=breadcrumbs.
redirect = `/${language}${req.url}`
}
}
if (!req.context.pages) throw new Error('req.context.pages not yet set')
- // Honor the reader's version preference on a URL that does not name a version.
- //
- // Without this, the cookie is only ever consulted on the bare homepage, so a deep link
- // from search, the product UI, or a bookmark silently serves Free/Pro/Team. See
- // github/technical-content#7227 for the measurements.
- //
- // This is deliberately its own branch rather than a tweak to `redirect` below, because
- // the ordinary path would emit a 301 for a language-prefixed URL. A redirect that
- // depends on a cookie has to stay a 302, or a browser caches one reader's preference
- // forever.
if (!redirect.includes('://')) {
const preference = getVersionPreference(
req.path,
@@ -151,18 +127,6 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
req.context.pages,
)
if (preference.vary && !preference.redirectTo) {
- // Only needed when we do not redirect. The redirect below calls
- // `languageAndVersionCacheControl`, which already lists `x-user-version`.
- //
- // We set it even though this response is not a redirect, because it still depends
- // on the cookie: a cached copy without this header would be served to readers whose
- // preference we should have honored.
- //
- // `append`, not `set`, so this survives the cache-control call that whatever
- // handles the request downstream makes. Those all append too, so nothing clobbers
- // it. The `varies on the cookie even for readers who have not set one` test in
- // `src/versions/tests/version-cookie.ts` asserts the served 200 really does carry
- // the header, so this holds even if that stops being true.
res.append('vary', 'x-user-version')
}
if (preference.redirectTo) {
@@ -175,7 +139,7 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
return next()
}
- // do not redirect if the redirected page can't be found
+ // Skip internal redirects whose target page is missing.
if (
!(
req.context.pages[removeQueryParams(redirect).replace(/\.md$/, '')] ||
@@ -183,15 +147,14 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
) &&
!redirect.includes('://')
) {
- // display error on the page in development, but not in production
- // include final full redirect path in the message
+ // Development responses expose the missing redirect target; production keeps the page clean.
if (process.env.NODE_ENV !== 'production' && req.context) {
req.context.redirectNotFound = redirect
}
return next()
}
- // do the redirect if the from-URL already had a language in it
+ // Language-prefixed and external redirects do not vary by language preference.
if (pathLanguagePrefixed(req.path) || redirect.includes('://')) {
defaultCacheControl(res)
} else {
@@ -203,27 +166,17 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
}
function getLanguage(req: ExtendedRequest, default_ = 'en') {
- // req.context.userLanguage, if it truthy, is always a valid supported
- // language. It's whatever was in the user's request in lib/languages.ts
+ // detect-language.ts limits userLanguage to supported cookie or Accept-Language values.
return req.context!.userLanguage || default_
}
function usePermanentRedirect(req: ExtendedRequest) {
- // If the redirect was to essentially swap `enterprise-server@latest`
- // for `enterprise-server@3.x` then, we definitely don't want to
- // do a permanent redirect.
- // When this is the case, we don't want a permanent redirect because
- // it could overzealously cache in the users' browser which could
- // be bad when whatever "latest" means changes.
+ // Redirects from enterprise-server@latest stay temporary because latest changes over time.
if (req.path.includes('/enterprise-server@latest')) return false
- // If the redirect involved injecting a language prefix, then don't
- // permanently redirect because that could overly cache in users'
- // browsers if we some day want to make the language redirect
- // depend on a cookie or 'Accept-Language' header.
+ // Language-prefixed paths redirect permanently here; injected prefixes fall through to temporary.
if (pathLanguagePrefixed(req.path)) return true
- // The default is to *not* do a permanent redirect.
return false
}
@@ -231,13 +184,10 @@ function removeQueryParams(redirect: string) {
return new URL(redirect, 'https://docs.github.com').pathname
}
+// Deprecated enterprise-server releases in deprecatedWithFunctionalRedirects have functional
+// redirects but no lookup entries or active req.context.pages for custom Next.js paths such as
+// /admin/release-notes.
function isDeprecatedVersion(path: string) {
- // When we rewrote how redirects work, from a lookup model to a
- // functional model, the enterprise-server releases that got
- // deprecated since then fall between the cracks. Especially
- // for custom NextJS page-like pages like /admin/release-notes
- // These URLs don't come from any remaining .json lookup file
- // and they're not active pages either (e.g. req.context.pages)
const split = path.split('/')
for (const version of deprecatedWithFunctionalRedirects) {
if (split.includes(`enterprise-server@${version}`)) {
diff --git a/src/redirects/middleware/language-code-redirects.ts b/src/redirects/middleware/language-code-redirects.ts
index d4561c734497..57fc324efffb 100644
--- a/src/redirects/middleware/language-code-redirects.ts
+++ b/src/redirects/middleware/language-code-redirects.ts
@@ -7,9 +7,7 @@ import { ExtendedRequest } from '@/types'
const redirectPatterns = Object.values(languages)
.map((language) => language.redirectPatterns || [])
.flat()
-// If the enabled languages have `.redirectPatterns`, combine them
-// into one which we only need to use to determine if we should bother
-// doing the redirect at all.
+// Combine enabled language redirectPatterns for a cheap precheck before scanning every pattern.
const combinedRedirectPatternRegex =
redirectPatterns.length > 0
? new RegExp(redirectPatterns.map((rex) => rex.source).join('|'))
@@ -19,26 +17,20 @@ const allRedirectPatterns = Object.values(languages)
.map((language) =>
(language.redirectPatterns || []).map((redirectPattern) => [language.code, redirectPattern]),
)
- .flat() as [string, RegExp][] // Seems TypeScript didn't understand the .flat()
+ .flat() as [string, RegExp][] // flat() loses tuple type inference.
-// This middleware handles redirects for mistyped language codes
-//
-// Examples:
-// /jp* -> /ja*
-// /zh-TW* -> /zh*
+// Redirect mistyped language codes, for example /jp* -> /ja* and /zh-TW* -> /zh*.
export default function languageCodeRedirects(
req: ExtendedRequest,
res: Response,
next: NextFunction,
) {
- // Only in the unlikely event that the `req.path` starts with one of these
- // prefixes do we bother looking up what the redirect should be.
+ // Only paths matching the combined precheck need per-language pattern lookup.
if (req.path.startsWith('/_next/static')) return next()
if (!combinedRedirectPatternRegex) return next()
if (!combinedRedirectPatternRegex.test(req.path)) return next()
- // This loop is almost never ever used so it doesn't have to be
- // particularly smart or fast.
+ // This rare path favors clarity over optimizing the pattern scan.
const matched = allRedirectPatterns.find(([, pattern]) => pattern.test(req.path))
if (matched) {
const [code, pattern] = matched
diff --git a/src/redirects/scripts/get-new-dotcom-path.ts b/src/redirects/scripts/get-new-dotcom-path.ts
index 57c87016b571..89ce2a21c208 100644
--- a/src/redirects/scripts/get-new-dotcom-path.ts
+++ b/src/redirects/scripts/get-new-dotcom-path.ts
@@ -1,9 +1,5 @@
-// [start-readme]
-//
-// Pass this script any old dotcom path (e.g., `articles/foo` or `foo.md`) and it
-// will output the new path in the content/github directory.
-//
-// [end-readme]
+// Finds the content/github path for an old dotcom path.
+// content/github no longer exists, so this script currently fails.
import assert from 'assert'
import { last } from 'lodash-es'
@@ -22,7 +18,6 @@ let filename: string = oldPath
if (filename.includes('/')) filename = last(filename.split('/')) as string
-// first check whether name is a category
const categoryDir = `${newDotcomDir}/${filename.replace(markdownRegex, '')}`
if (fs.existsSync(categoryDir)) {
@@ -30,7 +25,6 @@ if (fs.existsSync(categoryDir)) {
process.exit(0)
}
-// otherwise add extension and check whether it's a file
if (!filename.endsWith(markdownExtension)) filename = filename + markdownExtension
const newPath: string = execSync(`find ${newDotcomDir} -name ${filename}`).toString()
diff --git a/src/redirects/tests/content/redirect-orphans.ts b/src/redirects/tests/content/redirect-orphans.ts
index 5219ede4c86c..c975fa64181a 100644
--- a/src/redirects/tests/content/redirect-orphans.ts
+++ b/src/redirects/tests/content/redirect-orphans.ts
@@ -5,12 +5,11 @@ import { describe, expect, test, vi } from 'vitest'
import { loadPages } from '@/frame/lib/page-data'
describe('redirect orphans', () => {
- // Because calling `loadPages` will trigger a warmup, this can potentially
- // be very slow in CI. So we need a timeout.
+ // loadPages warms up the page cache, which can be slow in CI, so this test needs a timeout.
vi.setConfig({ testTimeout: 60 * 1000 })
test('no redirect_from entry has a trailing slash', async () => {
- // Only doing English because they're the only files we do PRs for.
+ // Only English files receive pull requests, so test English redirect_from entries.
const pageList = await loadPages(undefined, ['en'])
const errors = []
diff --git a/src/redirects/tests/ghae.ts b/src/redirects/tests/ghae.ts
index 300931301887..da17f2875475 100644
--- a/src/redirects/tests/ghae.ts
+++ b/src/redirects/tests/ghae.ts
@@ -1,9 +1,5 @@
-// We entirely removed GHAE but we still have to support legacy links.
-// The unit tests cover `getRedirect()` directly. These are end-to-end tests
-// that span the middleware, which uses `getRedirect()` internally.
-//
-// They matter because ghae is gone from the `allVersions` config object, so
-// these redirects are all that is left of it.
+// GitHub AE legacy links redirect through middleware; github-ae is absent from allVersions.
+// These end-to-end tests cover the middleware path; unit tests cover getRedirect directly.
import { describe, expect, test } from 'vitest'
@@ -31,7 +27,7 @@ describe('ghae redirects', () => {
test('ghae release notes', async () => {
const res = await head('/en/github-ae@latest/admin/release-notes')
expect(res.statusCode).toBe(301)
- // There is not an "equivalent" release notes page for enterprise-cloud
+ // No enterprise-cloud release notes equivalent exists.
expect(res.headers.location).toMatch('/en')
})
})
diff --git a/src/redirects/tests/redirects.ts b/src/redirects/tests/redirects.ts
index 93d5ebc52eae..138303aeb376 100644
--- a/src/redirects/tests/redirects.ts
+++ b/src/redirects/tests/redirects.ts
@@ -67,8 +67,7 @@ describe('redirects', () => {
})
test('have faq= not converted to query=', async () => {
- // Don't confuse `?faq=` for `?q=` just because they both start with `q=`
- // Docs internal #21945
+ // Keep faq intact while q becomes query.
const res = await get('/en/enterprise/admin?faq=pulls')
expect(res.statusCode).toBe(301)
const expected = `/en/enterprise-server@${enterpriseServerReleases.latest}/admin?faq=pulls`
@@ -115,7 +114,7 @@ describe('redirects', () => {
const res = await get('/')
expect(res.statusCode).toBe(302)
expect(res.headers.location).toBe('/en')
- // language specific caching
+ // Language redirects vary by language preference.
expect(res.headers['cache-control']).toContain('public')
expect(res.headers['cache-control']).toMatch(/max-age=\d+/)
expect(res.headers.vary).toContain('accept-language')
@@ -222,15 +221,12 @@ describe('redirects', () => {
test('frontmatter redirect', async () => {
const res = await get('/enterprise/2.12/user/articles/github-flavored-markdown')
- expect(res.statusCode).toBe(302) // because it doesn't have a language
+ expect(res.statusCode).toBe(302) // Missing language keeps this redirect temporary.
expect(res.headers.location).toBe('/enterprise/2.12/user/categories/writing-on-github/')
})
})
describe('enterprise admin', () => {
- // firstRestoredAdminGuides = 2.21
- // lastBeforeRestoredAdminGuides = 2.20
- // (these won't change but it's more convenient to use constants)
const { firstRestoredAdminGuides, getPreviousReleaseNumber, latest } = enterpriseServerReleases
const lastBeforeRestoredAdminGuides = getPreviousReleaseNumber(firstRestoredAdminGuides)
const enterpriseAdmin = `/en/enterprise-server@${latest}/admin`
@@ -321,7 +317,7 @@ describe('redirects', () => {
expect(res.headers.location).toBe(userArticle)
})
- // 2.16 was the first version where we moved /articles/foo to /github/<category>/foo
+ // Enterprise 2.16 is the redirect boundary for /articles/foo to /github/<category>/foo.
test('no product does not redirect to GitHub.com product in <=2.15', async () => {
const res = await get('/en/enterprise/2.15/user/articles/set-up-git')
expect(res.statusCode).toBe(200)
@@ -427,7 +423,7 @@ describe('redirects', () => {
test('no domain redirect on //example.com/', async () => {
const res = await get(`//example.com/`)
expect(res.statusCode).toBe(301)
- expect(res.headers.location).toBe(`/example.com`) // should not be //example.com
+ expect(res.headers.location).toBe(`/example.com`) // Guards against //example.com.
const res2 = await get(res.headers.location)
expect(res2.statusCode).toBe(404)
})
diff --git a/src/redirects/tests/routing/developer-site-redirects.ts b/src/redirects/tests/routing/developer-site-redirects.ts
index a3e6d6e9bbb8..dd8d4cdb113b 100644
--- a/src/redirects/tests/routing/developer-site-redirects.ts
+++ b/src/redirects/tests/routing/developer-site-redirects.ts
@@ -10,9 +10,7 @@ describe('developer redirects', () => {
vi.setConfig({ testTimeout: 60 * 1000 })
beforeAll(async () => {
- // The first page load takes a long time so let's get it out of the way in
- // advance to call out that problem specifically rather than misleadingly
- // attributing it to the first test
+ // Warm up the first page load so later failures point to the redirect under test.
await get('/v4')
})
@@ -70,27 +68,23 @@ describe('developer redirects', () => {
expectedFinalPath = '/en/rest'
expect(res.headers.location).toBe(expectedFinalPath)
- // REST subresources like activity notifications don't have their own page
- // anymore, so redirect to an anchor on the resource page
+ // REST subresource paths like activity notifications resolve under the resource page.
res = await get('/en/v3/activity')
expect(res.statusCode).toBe(301)
expectedFinalPath = '/en/rest/activity'
expect(res.headers.location).toBe(expectedFinalPath)
- // REST subresources like activity notifications don't have their own page
- // anymore, so redirect to an anchor on the resource page
+ // REST subresource paths like activity notifications resolve under the resource page.
res = await get('/en/v3/activity/notifications')
expect(res.statusCode).toBe(301)
expectedFinalPath = '/en/rest/activity/notifications'
expect(res.headers.location).toBe(expectedFinalPath)
- // trailing slashes are handled separately by the `slashes` module;
- // any request to a /v3 URL with a trailing slash will be redirected twice
+ // The slashes middleware removes trailing slash first, causing two redirects for /v3 URLs.
res = await get('/en/v3/activity/notifications/')
expect(res.statusCode).toBe(301)
expect(res.headers.location).toBe('/en/v3/activity/notifications')
- // non-reference redirects (e.g. guides)
res = await get('/en/v3/guides/basics-of-authentication')
expect(res.statusCode).toBe(301)
expectedFinalPath =
@@ -107,11 +101,9 @@ describe('developer redirects', () => {
}
if (!(label in FIXTURES)) throw new Error('unrecognized label')
const fixtures = readJsonFile(FIXTURES[label as keyof typeof FIXTURES])
- // Don't use a `Promise.all()` because it's actually slower
- // because of all the eventloop context switching.
+ // Avoid Promise.all here; event loop context switching makes it slower.
for (let [oldPath, newPath] of Object.entries(fixtures as Record<string, string>)) {
- // REST and GraphQL developer Enterprise paths with a version are only supported up to 2.21.
- // We make an exception to always redirect versionless paths to the latest version.
+ // Versioned developer Enterprise paths support up to 2.21; versionless paths use latest.
newPath = (newPath as string).replace(
'/enterprise-server/',
`/enterprise-server@${enterpriseServerReleases.latest}/`,
diff --git a/src/redirects/tests/routing/versionless-redirects.ts b/src/redirects/tests/routing/versionless-redirects.ts
index 6b62bc92f518..56cc1fb0b313 100644
--- a/src/redirects/tests/routing/versionless-redirects.ts
+++ b/src/redirects/tests/routing/versionless-redirects.ts
@@ -12,9 +12,8 @@ const VERSIONLESS_REDIRECTS_FILE = path.join(
'../../../../src/fixtures/fixtures/versionless-redirects.txt',
)
-// This test checks the default versioning redirect fallbacks described in lib/all-versions.ts.
-// The fixture now contains mock URLs instead of live URLs to prevent test failures when content is moved.
-// This ensures the redirect logic works correctly without being dependent on real content files.
+// These tests cover default versioning redirect fallbacks from lib/all-versions.ts.
+// The fixture uses mock URLs, so moved content cannot break them.
describe('versioned redirects', () => {
vi.setConfig({ testTimeout: 60 * 1000 })
diff --git a/src/redirects/tests/unit/get-redirect.ts b/src/redirects/tests/unit/get-redirect.ts
index 07a94b790293..25ce8fca5b1e 100644
--- a/src/redirects/tests/unit/get-redirect.ts
+++ b/src/redirects/tests/unit/get-redirect.ts
@@ -18,13 +18,9 @@ type TestContext = {
const previousEnterpriserServerVersion = supported[1]
describe('getRedirect basics', () => {
+ // Static developer.json redirects must win before legacy enterprise prefixes are normalized.
+ // For /enterprise/3.0/foo/bar, lookup happens before /enterprise-server@3.0 rewriting.
test('should sometimes not correct the version prefix', () => {
- // This essentially tests legacy entries that come from the
- // `developer.json` file. Normally, we would have first
- // rewritten `/enterprise/3.0` to `/enterprise-server@3.0`
- // and then, from there, worried about the remaining `/foo/bar`
- // part.
- // But some redirects from `developer.json` as old and static.
const uri = '/enterprise/3.0/foo/bar'
const ctx: TestContext = {
pages: {},
@@ -72,7 +68,7 @@ describe('getRedirect basics', () => {
},
}
expect(getRedirect('/free-pro-team@latest', ctx as unknown as Context)).toBe('/en')
- // Language is fine, but the version needs to be "removed"
+ // free-pro-team@latest is versionless, so the language prefix remains.
expect(getRedirect('/en/free-pro-team@latest', ctx as unknown as Context)).toBe('/en')
expect(getRedirect('/free-pro-team@latest/pizza', ctx as unknown as Context)).toBe('/en/pizza')
expect(getRedirect('/free-pro-team@latest/foo', ctx as unknown as Context)).toBe('/en/bar')
@@ -108,7 +104,7 @@ describe('getRedirect basics', () => {
},
redirects: {},
}
- // Replacing `/user` with `` worked because there exits a page of such name.
+ // The /user prefix can drop because the resulting page exists.
expect(
getRedirect(
`/enterprise-server@${previousEnterpriserServerVersion}/user/foo/bar`,
@@ -142,12 +138,12 @@ describe('getRedirect basics', () => {
ctx as unknown as Context,
),
).toBe(`/en/enterprise-server@${previousEnterpriserServerVersion}/something`)
- // but also respect redirects if there are some
+ // Respect redirects after normalizing the old enterprise prefix.
expect(
getRedirect(`/enterprise/${previousEnterpriserServerVersion}/foo`, ctx as unknown as Context),
).toBe(`/en/enterprise-server@${previousEnterpriserServerVersion}/bar`)
- // Unique snowflake pattern
+ // /enterprise/github paths map to enterprise-server github/admin paths.
expect(getRedirect('/enterprise/github/admin/foo', ctx as unknown as Context)).toBe(
`/en/enterprise-server@${latest}/github/admin/foo`,
)
@@ -158,8 +154,7 @@ describe('getRedirect basics', () => {
pages: {},
redirects: {},
}
- // Nothing's needed here because it's not /admin/guides and
- // it already has the enterprise-server prefix.
+ // No admin/guides rewrite applies when the path already has enterprise-server.
expect(
getRedirect(
`/en/enterprise-server@${latest}/admin/something/else`,
@@ -179,16 +174,14 @@ describe('getRedirect basics', () => {
[`/enterprise-server@${latestStable}/foo`]: `/enterprise-server@${latestStable}/bar`,
},
}
- // Nothing's needed here because it's not /admin/guides and
- // it already has the enterprise-server prefix.
+ // enterprise-server without a version resolves to latest stable before redirect lookup.
expect(getRedirect('/enterprise-server/foo', ctx as unknown as Context)).toBe(
`/en/enterprise-server@${latestStable}/bar`,
)
})
+ // Functional redirects cover enterprise-server 3.0 and later without lookup entries.
test('should work for some deprecated enterprise-server URLs too', () => {
- // Starting with enterprise-server 3.0, we have made redirects become
- // a *function* rather than a lookup on a massive object.
const ctx: TestContext = {
pages: {},
redirects: {},
@@ -282,7 +275,7 @@ describe('github-ae@latest', () => {
const ctx: TestContext = {
pages: {
'/en/foo': true,
- // Note the lack of an enterprise-cloud page here
+ // No enterprise-cloud page exists here, so GitHub AE falls back to Free/Pro/Team.
},
redirects: {
'/food': '/foo',
diff --git a/src/redirects/tests/unit/graphql-category-redirect.ts b/src/redirects/tests/unit/graphql-category-redirect.ts
index 670cd93cd333..58d09d9333ea 100644
--- a/src/redirects/tests/unit/graphql-category-redirect.ts
+++ b/src/redirects/tests/unit/graphql-category-redirect.ts
@@ -11,8 +11,7 @@ describe('applyGraphqlCategoryRedirect', () => {
})
test('rewrites a legacy scalar URL with language prefix', () => {
- // Boolean is a built-in GraphQL scalar with no @docsCategory, so it falls
- // to the `other` bucket.
+ // Built-in GraphQL scalars have no @docsCategory, so they fall into the other bucket.
expect(applyGraphqlCategoryRedirect('/en/graphql/reference/scalars#boolean')).toBe(
'/en/graphql/reference/other#scalar-boolean',
)
@@ -31,7 +30,7 @@ describe('applyGraphqlCategoryRedirect', () => {
})
test('uses the category from the schema map when annotated', () => {
- // `Repository` is annotated with `@docsCategory(name: "repos")` upstream.
+ // Repository has @docsCategory(name: "repos") in the upstream schema.
expect(applyGraphqlCategoryRedirect('/en/graphql/reference/objects#repository')).toBe(
'/en/graphql/reference/repos#object-repository',
)
@@ -44,7 +43,7 @@ describe('applyGraphqlCategoryRedirect', () => {
})
test('handles `input-objects` kind segment', () => {
- // CustomPropertyValueInput is categorized as `repos` in the fpt schema.
+ // The fpt schema categorizes CustomPropertyValueInput as repos.
expect(
applyGraphqlCategoryRedirect('/en/graphql/reference/input-objects#custompropertyvalueinput'),
).toBe('/en/graphql/reference/repos#input-object-custompropertyvalueinput')
diff --git a/src/redirects/tests/unit/precompile.ts b/src/redirects/tests/unit/precompile.ts
index e702ee09205e..b4d884c9b708 100644
--- a/src/redirects/tests/unit/precompile.ts
+++ b/src/redirects/tests/unit/precompile.ts
@@ -13,8 +13,8 @@ vi.mock('../../lib/exception-redirects', () => ({
const { default: precompileRedirects } = await import('../../lib/precompile')
const { default: generateRedirectsForPermalinks } = await import('../../lib/permalinks')
-// Minimal stand-in for a Page instance. precompileRedirects() only relies on
-// `languageCode`, `permalinks`, and `buildRedirects()`.
+// makePage supplies only the Page fields precompileRedirects needs: languageCode, permalinks, and
+// buildRedirects.
function makePage(
languageCode: string,
permalinks: { pageVersion: string; hrefWithoutLanguage: string }[],
@@ -36,7 +36,7 @@ function makePage(
describe('precompileRedirects', () => {
test('removes a redirect_from-generated redirect that clobbers a live old-page permalink, but keeps it for versions where the old page is absent', async () => {
- // The old page only exists in GHES 3.14.
+ // The old page exists only in GHES 3.14.
const oldPage = makePage(
'en',
[
@@ -48,9 +48,7 @@ describe('precompileRedirects', () => {
[],
)
- // The replacement page exists in both 3.14 and 3.15, and declares
- // `redirect_from: ['/foo']`, which would otherwise clobber the old
- // page's live permalink in 3.14.
+ // redirect_from on the replacement page must not clobber the old GHES 3.14 permalink.
const newPage = makePage(
'en',
[
@@ -68,12 +66,10 @@ describe('precompileRedirects', () => {
const redirects = await precompileRedirects([oldPage, newPage])
- // The old page's live permalink in 3.14 must not be clobbered by the
- // replacement page's redirect_from.
+ // The GHES 3.14 old-page permalink wins over the replacement page's redirect_from.
expect(redirects['/enterprise-server@3.14/foo']).toBeUndefined()
- // But in 3.15, where the old page doesn't exist, the redirect must
- // still be there.
+ // GHES 3.15 lacks the old page, so redirect_from still creates the redirect.
expect(redirects['/enterprise-server@3.15/foo']).toBe('/enterprise-server@3.15/bar')
})
})
diff --git a/src/redirects/tests/version-preference.ts b/src/redirects/tests/version-preference.ts
index f6a9e6a53bfa..f9c27ae37b57 100644
--- a/src/redirects/tests/version-preference.ts
+++ b/src/redirects/tests/version-preference.ts
@@ -6,9 +6,8 @@ import { latest } from '@/versions/lib/enterprise-server-releases'
const GHEC = 'enterprise-cloud@latest'
const GHES = `enterprise-server@${latest}`
-// A stand-in for `req.context.pages`, which is keyed by full versioned permalink.
-// `/actions/versioned` exists in all three versions, `/actions/fpt-only` only in the
-// unversioned one.
+// pages stands in for req.context.pages, keyed by full versioned permalink.
+// /actions/versioned exists in all three versions; /actions/fpt-only exists only unversioned.
const pages = Object.fromEntries(
[
'/en/actions/versioned',
@@ -27,14 +26,13 @@ describe('pathNamesAVersion', () => {
['/en/enterprise-cloud@latest/actions/foo', true],
['/en/free-pro-team@latest/actions/foo', true],
['/en/enterprise-server@latest/actions/foo', true],
- // Deprecated releases are not keys of `allVersions`, but naming one is still
- // an explicit request and has to beat the cookie.
+ // Deprecated releases are absent from allVersions, but explicit version paths beat the cookie.
['/en/enterprise-server@3.0/actions/foo', true],
['/en/github-ae@latest/actions/foo', true],
- // Legacy shapes that carry no `@`.
+ // Legacy shapes without @ still name a version.
['/en/enterprise-server/3.9/actions/foo', true],
['/en/enterprise/3.3/actions/foo', true],
- // No version named.
+ // These paths name no version.
['/en/actions/foo', false],
['/actions/foo', false],
['/en', false],
@@ -56,9 +54,8 @@ describe('getVersionPreference', () => {
expect(getVersionPreference(path, path, GHEC, pages)).toEqual({ vary: false })
})
- // The escape hatch. `getRedirect` strips `/free-pro-team@latest` before the middleware
- // gets here, so the resolved path looks unversioned. Only the request path still shows
- // that the reader asked for Free/Pro/Team on purpose.
+ // free-pro-team@latest is an escape hatch: getRedirect strips it before this helper runs.
+ // The original request path still proves the reader explicitly asked for Free/Pro/Team.
test('leaves an explicit free-pro-team URL alone even after the prefix is stripped', () => {
expect(
getVersionPreference(
@@ -88,9 +85,8 @@ describe('getVersionPreference', () => {
).toEqual({ vary: true, redirectTo: `/en/${GHES}/actions/versioned` })
})
- // The partial case: this article has a version the cookie could have selected, just not
- // the one this reader asked for. No redirect, but the response still depends on the
- // cookie, so it must not be cached as though it were the same for everyone.
+ // If the cookie names a version the article lacks, the response still depends on the cookie.
+ // Vary prevents caches from serving that fallback response to readers with other preferences.
test('varies without redirecting when the cookie names a version this article lacks', () => {
expect(
getVersionPreference('/en/actions/ghec-only', '/en/actions/ghec-only', GHES, pages),
@@ -139,8 +135,7 @@ describe('getVersionPreference', () => {
})
})
- // The redirect target names a version, so the next request short-circuits on
- // `pathNamesAVersion` and cannot bounce back.
+ // Versioned redirect targets short-circuit on pathNamesAVersion, so they cannot bounce back.
test('cannot loop', () => {
const first = getVersionPreference(
'/en/actions/versioned',
diff --git a/src/release-notes/lib/release-notes-utils.ts b/src/release-notes/lib/release-notes-utils.ts
index 727a59e91cae..8dd3a9a0afcf 100644
--- a/src/release-notes/lib/release-notes-utils.ts
+++ b/src/release-notes/lib/release-notes-utils.ts
@@ -3,13 +3,8 @@ import { supported, latestStable, latest } from '@/versions/lib/enterprise-serve
import { renderContent } from '@/content-render/index'
import type { Context, GHESReleasePatch, ReleaseNotes } from '@/types'
-/**
- * Create an array of release note objects and sort them by number.
- * Turn { [key]: { notes, intro, date, sections... } }
- * Into [{ version, patches: [ {notes, intro, date, sections... }] }]
- */
export function formatReleases(releaseNotes: ReleaseNotes) {
- // Dot notation, highest first.
+ // Sort dot-formatted release numbers from highest to lowest.
const sortedReleaseNumbers = Object.keys(releaseNotes)
.map((r) => r.replace(/-/g, '.'))
.sort((a, b) => supported.indexOf(a) - supported.indexOf(b))
@@ -19,7 +14,7 @@ export function formatReleases(releaseNotes: ReleaseNotes) {
const patches = Object.keys(notesPerVersion)
.filter((patchNumber) => !notesPerVersion[patchNumber].deprecated)
.map((patchNumber) => {
- // Change version-rc1 to version-rc.1 to make these proper semver RC versions.
+ // Normalize rc1 to rc.1 for release-note version strings.
const patchNumberSemver = patchNumber.replace(/rc/, 'rc.')
return {
...notesPerVersion[patchNumber],
@@ -34,20 +29,12 @@ export function formatReleases(releaseNotes: ReleaseNotes) {
return {
version: releaseNumber,
patches,
- // Lets callers drop release candidates,
- // like the "Supported releases" list on the product landing page.
- // An RC only exists while `latestStable` isn't `latest`.
+ // Lets consumers drop release candidates from supported-release lists.
isReleaseCandidate: latest !== latestStable && releaseNumber === latest,
}
})
}
-/**
- * Render each note in the given patch, by looping through the
- * sections and rendering either `note` or `note.notes` in the
- * case of a sub-section.
- * Returns [{version, patchVersion, intro, date, sections: { features: [], bugs: []...}}]
- */
export async function renderPatchNotes(
patches: GHESReleasePatch[],
ctx: Context,
@@ -58,15 +45,11 @@ export async function renderPatchNotes(
const renderedPatch: GHESReleasePatch = { ...patch, sections: {} }
renderedPatch.intro = await renderContent(patch.intro, ctx)
- // sections looks like { features: [], bugs: [], ... }
const renderedSections = Object.fromEntries(
await Promise.all(
Object.entries(patch.sections).map(async ([sectionType, sectionArray]) => {
- // sectionType is things like 'features', 'bugs', etc.
- // sectionArray is things like [ { heading, notes: [] } ]
const renderedSectionArray = await Promise.all(
sectionArray.map(async (note) => {
- // `note` is either a string or { heading, notes: [] }
if (typeof note === 'string') {
return renderContent(note, ctx)
} else if (typeof note === 'object' && 'heading' in note && 'notes' in note) {
diff --git a/src/release-notes/middleware/get-release-notes.ts b/src/release-notes/middleware/get-release-notes.ts
index 897bb218f653..c4887cf91b74 100644
--- a/src/release-notes/middleware/get-release-notes.ts
+++ b/src/release-notes/middleware/get-release-notes.ts
@@ -1,39 +1,26 @@
import { getDataByLanguage, getDeepDataByLanguage } from '@/data-directory/lib/get-data'
import type { GHESReleasePatch, ReleaseNotes } from '@/types'
-// Widen the union if we ever support release notes for another product.
type ReleaseNotesPrefix = 'enterprise-server'
export function getReleaseNotes(prefix: ReleaseNotesPrefix, langCode: string) {
- // Use English as the foundation, then we'll try to load each individual
- // data/release-notes/**/*.yml file from the translation.
- // If the language is 'en', don't even bother merging.
+ // English release notes define the file set because translation directories can retain stale files.
const releaseNotes = getDeepDataByLanguage(`release-notes.${prefix}`, 'en') as ReleaseNotes
if (langCode === 'en') {
return releaseNotes
}
- // The reason we're doing this is because we can't trust
- // getDeepDataByLanguage() in the translations because it depends on
- // loading in all possible files in the directory. Translations often
- // don't delete files, so we use the English data as a guide for which
- // data files to bother reading.
-
- // `getDeepDataByLanguage()` returns a mutable object from a memoize cache,
- // so build a new one rather than mutating it.
+ // getDeepDataByLanguage returns a mutable object from a memoize cache.
const translatedReleaseNotes: ReleaseNotes = {}
for (const [majorVersion, releases] of Object.entries(releaseNotes)) {
- // Major version is things like '3-7'
translatedReleaseNotes[majorVersion] = {}
for (const minorVersion of Object.keys(releases)) {
- // Minor version is things like '0-rc1' or '3'
const data = getDataByLanguage(
`release-notes.${prefix}.${majorVersion}.${minorVersion}`,
langCode,
) as GHESReleasePatch
- // If any section was mistranslated into something other than an array,
- // fall back to English.
+ // Fall back to English when a translated section is not an array.
const validSections = Object.values(data.sections).every((sectionValue) =>
Array.isArray(sectionValue),
)
diff --git a/src/release-notes/middleware/ghes-release-notes.ts b/src/release-notes/middleware/ghes-release-notes.ts
index 7b2abe3461ba..6ce4b006be76 100644
--- a/src/release-notes/middleware/ghes-release-notes.ts
+++ b/src/release-notes/middleware/ghes-release-notes.ts
@@ -17,25 +17,17 @@ export default async function ghesReleaseNotesContext(
const [requestedPlan, requestedRelease] = req.context.currentVersion.split('@')
if (requestedPlan !== 'enterprise-server') return next()
- // Forced to English.
- // The Markdown in data/release-notes/**/*.yml spells out product names
- // instead of using Liquid variables,
- // so translators render "Le GitHubbe Cöpilotte" instead of "GitHub Copilot".
- // Revisit once those sources use `{% data variables.product.* %}`.
+ // Force English because some release-note entries still spell out product names.
const ghesReleaseNotes = getReleaseNotes('enterprise-server', 'en')
- // If the requested GHES release isn't found in data/release-notes/enterprise-server/*,
- // and it IS a valid GHES release, try being helpful and redirecting to the old location.
- // Otherwise, 404.
+ // Valid releases missing local notes redirect to enterprise.github.com; others return 404.
if (!Object.keys(ghesReleaseNotes).includes(requestedRelease.replace(/\./, '-'))) {
return all.includes(requestedRelease)
? res.safeRedirect(`https://enterprise.github.com/releases/${requestedRelease}.0/notes`)
: next()
}
- // For example, the URL is something like /enterprise-server@3.7/xxx/admin
- // or /enterprise-server@3.7/xxxx/release-notes
- // Then it should not bother because it'll be a 404 anyway.
+ // Paths under the right version but wrong page still return 404 through the normal middleware.
if (!req.context.page) return next()
req.context.ghesReleases = formatReleases(ghesReleaseNotes)
@@ -44,22 +36,17 @@ export default async function ghesReleaseNotesContext(
if (!matchedReleaseNotes) throw new Error('Release notes not found')
const currentReleaseNotes = matchedReleaseNotes.patches
- // The release notes themselves are already forced to English.
- // This forces the reusables to match,
- // while AUTOTITLE links stay in the reader's language.
+ // Render reusables in English while AUTOTITLE links stay in the reader's language.
const originalLanguage = req.context.currentLanguage
req.context.autotitleLanguage = originalLanguage
req.context.currentLanguage = 'en'
try {
- // Render the release notes Markdown.
req.context.ghesReleaseNotes = await executeWithFallback(
req.context,
() => renderPatchNotes(currentReleaseNotes, req.context!),
(enContext: Context) => {
- // Something in the release notes ultimately caused a Liquid
- // rendering error. Let's start over and gather the English release
- // notes instead.
+ // Unreachable while currentLanguage is forced to en; rebuild props if that changes.
enContext.ghesReleases = formatReleases(ghesReleaseNotes)
const enMatchedNotes = enContext.ghesReleases!.find((r) => r.version === requestedRelease)
@@ -72,12 +59,11 @@ export default async function ghesReleaseNotesContext(
req.context.currentLanguage = originalLanguage
}
- // GHES release notes on docs started with 2.20 but older release notes exist on enterprise.github.com.
- // So we want to use _all_ GHES versions when calculating next and previous releases.
+ // latestPatch comes from local notes; latestRelease comes from supported release metadata.
req.context.latestPatch = req.context.ghesReleaseNotes![0].version
req.context.latestRelease = latestStable
- // Add convenience props for "Supported releases" section on GHES Admin landing page (NOT release notes).
+ // Previous-release links include older GHES releases hosted on enterprise.github.com.
for (const release of req.context.ghesReleases) {
release.firstPreviousRelease = all[all.findIndex((v) => v === release.version) + 1]
release.secondPreviousRelease =
diff --git a/src/release-notes/pages/release-notes.tsx b/src/release-notes/pages/release-notes.tsx
index 8408f65222a2..6b4718ab6a16 100644
--- a/src/release-notes/pages/release-notes.tsx
+++ b/src/release-notes/pages/release-notes.tsx
@@ -21,9 +21,7 @@ type Props = {
}
export default function ReleaseNotes({ mainContext, ghesContext }: Props) {
if (!ghesContext) {
- // (Jan 2024) If we some day have more types of release notes, we'll
- // need to make this more forgiving.
- // This component used to cater for GHAE too when that existed.
+ // GHES is the only supported release-notes product.
throw new Error('GHES is the only option')
}
return (
@@ -41,8 +39,7 @@ export const getServerSideProps: GetServerSideProps<Props> = async (
const req = context.req as unknown as ExtendedRequest
const res = context.res as unknown as Response
- // `allVersions[X]` carries more than the components need,
- // so pick only the keys they use.
+ // allVersions entries carry more than these components need, so pick only the keys they use.
const currentVersion = pick(req.context!.allVersions?.[req.context!.currentVersion!] || {}, [
'plan',
'planTitle',
diff --git a/src/release-notes/tests/release-notes.ts b/src/release-notes/tests/release-notes.ts
index 1805dd1539d8..1af118febe9a 100644
--- a/src/release-notes/tests/release-notes.ts
+++ b/src/release-notes/tests/release-notes.ts
@@ -5,8 +5,7 @@ import enterpriseServerReleases from '@/versions/lib/enterprise-server-releases'
import { get, getDOM } from '@/tests/helpers/e2etest'
import Page from '@/frame/lib/page'
-// The English content page's `versions:` frontmatter is the source
-// of (convenient) truth about which versions of this page is available.
+// The English page versions frontmatter defines the versions this page supports.
const page = await Page.init({
basePath: 'content',
relativePath: 'admin/release-notes.md',
@@ -21,7 +20,7 @@ describe('server', () => {
const res = await get('/admin/release-notes')
expect(res.statusCode).toBe(302)
expect(res.headers.location).toBe(
- // Note that English is the default fallback for redirects
+ // English remains the default fallback for redirects.
`/en/enterprise-server@${enterpriseServerReleases.latest}/admin/release-notes`,
)
})
diff --git a/src/secret-scanning/components/SecretScanningTable.tsx b/src/secret-scanning/components/SecretScanningTable.tsx
index 6173e89f4445..b1d0fbf0295d 100644
--- a/src/secret-scanning/components/SecretScanningTable.tsx
+++ b/src/secret-scanning/components/SecretScanningTable.tsx
@@ -14,9 +14,8 @@ const PAGE_SIZE = 25
// Identifies this table in the docs.v0.TableInteractionEvent analytics.
const TABLE_INTERACTION_NAME = 'secret-scanning-patterns'
-// Maps DataTable column ids to the canonical analytics field name so that a
-// filter and a sort on the same column report the same
-// table_interaction_field_name. Filter keys already use these canonical names.
+// Canonical analytics field names keep filter and sort events for the same column
+// grouped together. Filter keys already use these names.
const COLUMN_FIELD_NAMES: Record<string, string> = {
provider: 'provider',
supportedSecret: 'secret',
@@ -59,7 +58,7 @@ export function SecretScanningTable({ data }: { data: SecretScanningData[] }) {
const [sortColumn, setSortColumn] = useState<string | undefined>(undefined)
const [sortDirection, setSortDirection] = useState<'ASC' | 'DESC'>('ASC')
- // Emit a TableInteractionEvent for analytics (github/docs-engineering#6593).
+ // TableInteractionEvent feeds search, filter, sort, and pagination analytics.
const trackInteraction = useCallback(
(interactionType: TableInteractionType, fieldName?: string, fieldValue?: string) => {
sendEvent({
@@ -77,8 +76,7 @@ export function SecretScanningTable({ data }: { data: SecretScanningData[] }) {
const debouncedTrackSearchRef = useRef<ReturnType<typeof debounce> | null>(null)
useEffect(() => {
debouncedTrackSearchRef.current = debounce((query: string) => {
- // Sanitize before logging: users may paste a real secret into this
- // table's search to check support, and the query is sent to analytics.
+ // Sanitize before analytics because users can paste real secrets into this support search.
trackInteraction('search', 'search', sanitizeSearchQuery(query))
}, 500)
return () => {
@@ -263,8 +261,7 @@ export function SecretScanningTable({ data }: { data: SecretScanningData[] }) {
field: 'supportedSecret',
width: '280px',
renderCell: (row) => {
- // The middleware appends HTML for duplicates; strip it.
- // Also handle </br> and <br/> separators in the raw secretType.
+ // Remove duplicate token-versions link; convert raw <br> separators to commas.
const cleanSecretType = row.secretType
.replace(/ <br\/><a href="#token-versions">Token versions<\/a>/, '')
.replace(/<\/?br\s*\/?>/gi, ', ')
diff --git a/src/secret-scanning/pages/api/patterns.ts b/src/secret-scanning/pages/api/patterns.ts
index d8fb0c71369c..38615b48f155 100644
--- a/src/secret-scanning/pages/api/patterns.ts
+++ b/src/secret-scanning/pages/api/patterns.ts
@@ -2,7 +2,7 @@ import type { NextApiRequest, NextApiResponse } from 'next'
import { getSecretScanningData } from '@/secret-scanning/lib/get-secret-scanning-data'
import path from 'path'
-// Returns the cached pattern data as JSON. No HTML rendering here.
+// The API serves cached pattern data as JSON without HTML rendering.
export default async function handler(req: NextApiRequest, res: NextApiResponse) {
const version = (req.query.version as string) || 'fpt'
const filepath = path.join(
@@ -14,7 +14,7 @@ export default async function handler(req: NextApiRequest, res: NextApiResponse)
try {
const data = await getSecretScanningData(filepath)
- // The data only changes on deploy, so cache hard.
+ // The data changes only on deploy, so cache hard.
res.setHeader('Cache-Control', 'public, max-age=3600, s-maxage=86400')
res.json(data)
} catch {
diff --git a/src/secret-scanning/pages/supported-secret-scanning-patterns.tsx b/src/secret-scanning/pages/supported-secret-scanning-patterns.tsx
index 7307840715cc..594e413ab6d5 100644
--- a/src/secret-scanning/pages/supported-secret-scanning-patterns.tsx
+++ b/src/secret-scanning/pages/supported-secret-scanning-patterns.tsx
@@ -43,7 +43,7 @@ export const getServerSideProps: GetServerSideProps<Props> = async (context) =>
addUINamespaces(req, mainContext.data.ui, ['secret_scanning'])
const automatedPageContext = getAutomatedPageContextFromRequest(req)
- // The middleware already loads secretScanningData into req.context
+ // secretScanning middleware loads secretScanningData into req.context.
const patterns = req.context?.secretScanningData ?? []
return {
props: {
diff --git a/src/secret-scanning/scripts/sync.ts b/src/secret-scanning/scripts/sync.ts
index 547767aaa2c6..3f1976d014d4 100755
--- a/src/secret-scanning/scripts/sync.ts
+++ b/src/secret-scanning/scripts/sync.ts
@@ -1,12 +1,6 @@
-/**
- * Required env variables:
- *
- * GITHUB_TOKEN
- *
- * Syncs the
- * https://github.com/github/token-scanning-service/blob/main/docs/public-docs
- * directory to src/secret-scanning/data/pattern-docs
- */
+// Required env variable: GITHUB_TOKEN.
+// Syncs https://github.com/github/token-scanning-service/blob/main/docs/public-docs into
+// src/secret-scanning/data/pattern-docs.
import { writeFile, mkdir } from 'fs/promises'
import { load, dump } from 'js-yaml'
import path from 'path'
diff --git a/src/secret-scanning/tests/liquid-evaluation.ts b/src/secret-scanning/tests/liquid-evaluation.ts
index 63669f985fd3..55a98e8d1fe0 100644
--- a/src/secret-scanning/tests/liquid-evaluation.ts
+++ b/src/secret-scanning/tests/liquid-evaluation.ts
@@ -15,8 +15,8 @@ const { targetFilename } = JSON.parse(
readFileSync('src/secret-scanning/lib/config.json', 'utf8'),
) as { targetFilename: string }
-// Both hasValidityCheck and hasExtendedMetadata can be emitted by token-scanning-service
-// as a Liquid conditional that resolves to false on GHES and true elsewhere.
+// token-scanning-service can emit hasValidityCheck and hasExtendedMetadata as Liquid
+// conditionals that resolve false on GHES and true elsewhere.
const ghesConditional = '{% ifversion ghes %}false{% else %}true{% endif %}'
const makeEntry = (): SecretScanningData =>
diff --git a/src/secret-scanning/tests/rendering.ts b/src/secret-scanning/tests/rendering.ts
index e169df44e0d8..2332b67337ce 100644
--- a/src/secret-scanning/tests/rendering.ts
+++ b/src/secret-scanning/tests/rendering.ts
@@ -20,7 +20,7 @@ describe('secret-scanning pipeline', () => {
const url =
'/en/enterprise-server@3.11/enterprise-cloud@latest/code-security/secret-scanning/introduction/supported-secret-scanning-patterns'
const res = await get(url)
- // It should probably be a 404 because the URL is invalid, but definitely not a 500
+ // Invalid double-version URLs can return 404, but they must not return 500.
expect(res.statusCode).not.toBe(500)
})
})
diff --git a/src/shielding/middleware/handle-invalid-headers.ts b/src/shielding/middleware/handle-invalid-headers.ts
index 857434e2516c..f498dcb6d277 100644
--- a/src/shielding/middleware/handle-invalid-headers.ts
+++ b/src/shielding/middleware/handle-invalid-headers.ts
@@ -3,11 +3,8 @@ import type { Response, NextFunction } from 'express'
import { ExtendedRequest } from '@/types'
const INVALID_HEADER_KEYS = [
- // Next.js will pick this up and override the status code.
- // We don't want that to happen because `x-invoke-status: 203` can
- // trigger the CDN to cache it.
- // It can also trigger a 500 error because the header is not used
- // correctly.
+ // Next.js treats x-invoke-status as the response status, which can make the CDN cache 203s
+ // or turn malformed requests into 500s.
'x-invoke-status',
]
@@ -18,10 +15,7 @@ export default function handleInvalidNextPaths(
) {
const header = INVALID_HEADER_KEYS.find((key) => req.headers[key])
if (header) {
- // There's no point attempting to set a cache-control on this.
- // The CDN will not cache if the status code is not a success
- // and not a 404.
-
+ // The CDN does not cache non-success, non-404 responses.
res.status(400).type('text').send('Invalid request headers')
return
}
diff --git a/src/shielding/middleware/handle-invalid-nextjs-paths.ts b/src/shielding/middleware/handle-invalid-nextjs-paths.ts
index f2ef1f5c8de2..8141544b5d7b 100644
--- a/src/shielding/middleware/handle-invalid-nextjs-paths.ts
+++ b/src/shielding/middleware/handle-invalid-nextjs-paths.ts
@@ -6,16 +6,13 @@ import { ExtendedRequest } from '@/types'
const STATSD_KEY = 'middleware.handle_invalid_nextjs_paths'
+// Development needs /_next/static/webpack and /_next/webpack-hmr.
+// Production blocks /_next/ paths unless they start with /_next/data, plus __nextFallback requests.
export default function handleInvalidNextPaths(
req: ExtendedRequest,
res: Response,
next: NextFunction,
) {
- // For example, `/_next/bin/junk.css`.
- // The reason for depending on checking NODE_ENV is that in development,
- // the Nextjs server will send things like /_next/static/webpack/...
- // or /_next/webpack-hmr.
- // In local dev, we don't get these penetration-testing looking requests.
if (
process.env.NODE_ENV !== 'development' &&
((req.path.startsWith('/_next/') && !req.path.startsWith('/_next/data')) ||
diff --git a/src/shielding/middleware/handle-invalid-paths.ts b/src/shielding/middleware/handle-invalid-paths.ts
index 7b259d55c941..6988c6f4adba 100644
--- a/src/shielding/middleware/handle-invalid-paths.ts
+++ b/src/shielding/middleware/handle-invalid-paths.ts
@@ -3,10 +3,7 @@ import type { Response, NextFunction } from 'express'
import { defaultCacheControl } from '@/frame/middleware/cache-control'
import { ExtendedRequest } from '@/types'
-// We'll check if the current request path is one of these, or ends with
-// one of these.
-// These are clearly intentional "guesses" made by some sort of
-// pen-testing bot.
+// These path guesses come from penetration-testing bots.
const JUNK_STARTS = ['///', '/\\', '/\\.']
const JUNK_ENDS = [
'/package.json',
@@ -28,10 +25,9 @@ const JUNK_PATHS = new Set([
'/_next',
])
-// Basename is the last token of the path when split by `/`.
-// For example `/foo/bar/baz` has a basename of `baz`.
+// Basenames catch nested probes such as /en/code-security/.env.
const JUNK_BASENAMES = new Set([
- // E.g. /en/code-security/.env
+ // Keep .env separate from .env.local matching below.
'.env',
])
@@ -51,18 +47,16 @@ function isJunkPath(path: string) {
}
const basename = path.split('/').pop()
- // E.g. `/billing/.env.local` or `/billing/.env_sample`
+ // Matches /billing/.env.local and /billing/.env_sample.
if (basename && /^\.env(.|_)[\w.]+/.test(basename)) return true
if (basename && JUNK_BASENAMES.has(basename)) return true
- // Prevent various malicious injection attacks targeting Next.js
+ // Block malformed Next.js paths before Next.js handles them.
if (path.match(/^\/_next[^/]/) || path === '/_next/data' || path === '/_next/data/') {
return true
}
- // We currently don't use next/image for any images.
- // This could change in the future but right now can just 404 on these
- // so we don't have to deal with any other errors.
+ // Docs does not use next/image, so these paths can 404 before Next.js handles them.
if (path.startsWith('/_next/image')) {
return true
}
@@ -76,8 +70,7 @@ export default function handleInvalidPaths(
next: NextFunction,
) {
if (isJunkPath(req.path)) {
- // We can let the CDN cache these responses because they are not going
- // to suddenly work in the next deployment.
+ // The CDN can cache scanner responses because the paths will not work in the next deployment.
defaultCacheControl(res)
res.status(404).type('text').send('Not found')
return
diff --git a/src/shielding/middleware/handle-invalid-query-string-values.ts b/src/shielding/middleware/handle-invalid-query-string-values.ts
index 324bbaaa5433..5e738bebb608 100644
--- a/src/shielding/middleware/handle-invalid-query-string-values.ts
+++ b/src/shielding/middleware/handle-invalid-query-string-values.ts
@@ -11,28 +11,13 @@ const logger = createLogger(import.meta.url)
const STATSD_KEY = 'middleware.handle_invalid_querystring_values'
-// Hi future reader!
-// If there are query strings whose values are static and predictable,
-// type them in here.
-// It can't be something like `?query=...` because its value is highly
-// dynamic.
-// At the time of writing, these will match independent of location. A
-// possible extension, in the future, is to make the value match
-// dependent on the location. For example, you might want to express
-// that the values of `?platform=...` should be none when the path is
-// something like `/en/search`.
+// Recognized values must be static across pages; dynamic values such as query stay out.
+// Add path-aware matching if a key needs different values on pages such as /en/search.
const RECOGNIZED_VALUES = {
platform: allPlatforms as string[],
tool: Object.keys(allTools),
}
-// So we can look up if a key in the object is actually present
-// and not a built in.
-// Otherwise...
-//
-// > const myObj = {foo: 'bar'}
-// > 'constructor' in myObj
-// true
-//
+// Use a Set so built-in object properties such as constructor do not count as recognized keys.
const RECOGNIZED_VALUES_KEYS = new Set(Object.keys(RECOGNIZED_VALUES))
export default function handleInvalidQuerystringValues(
@@ -55,8 +40,7 @@ export default function handleInvalidQuerystringValues(
validValues,
})
}
- // Some value is not recognized. Redirect to the current URL
- // but with that query string key removed.
+ // Redirect after removing the query key that contains an unrecognized value.
const sp = new URLSearchParams(query as Record<string, string>)
sp.delete(key)
@@ -72,7 +56,7 @@ export default function handleInvalidQuerystringValues(
}
}
- // For example ?foo[bar]=baz (but not ?foo=bar&foo=baz)
+ // Reject ?foo[bar]=baz, but not ?foo=bar&foo=baz.
if (value instanceof Object && !Array.isArray(value)) {
const message = 'Invalid query string'
defaultCacheControl(res)
diff --git a/src/shielding/middleware/handle-invalid-query-strings.ts b/src/shielding/middleware/handle-invalid-query-strings.ts
index df7c81577c12..df7e85fe95b4 100644
--- a/src/shielding/middleware/handle-invalid-query-strings.ts
+++ b/src/shielding/middleware/handle-invalid-query-strings.ts
@@ -23,36 +23,36 @@ const RECOGNIZED_KEYS_BY_PREFIX = {
}
const RECOGNIZED_KEYS_BY_ANY = new Set([
- // Learning track pages
+ // Learning track pages add these keys.
'learn',
'learnProduct',
- // Platform picker
+ // The platform picker adds this key.
'platform',
- // Tool picker
+ // The tool picker adds this key.
'tool',
- // When apiVersion isn't the only one. E.g. ?apiVersion=XXX&tool=vscode
+ // API pages can combine apiVersion with picker keys such as tool.
'apiVersion',
- // Search results page
+ // Search results pages read this key.
'query',
- // Any page, Search Overlay
+ // The search overlay can add these keys on any page.
'search-overlay-input',
'search-overlay-open',
'search-overlay-ask-ai',
- // The drop-downs on "Webhook events and payloads"
+ // Webhook events pages use actionType for drop-down filtering.
'actionType',
- // Landing page article grid filters
+ // Landing page article grids use these filter keys.
'articles-category',
'articles-filter',
'articles-page',
- // Legacy domain tracking parameter (no longer processed but still recognized)
+ // Recognize the legacy ghdomain parameter even though Docs no longer processes it.
'ghdomain',
- // UTM campaign tracking
+ // UTM campaign links add these keys.
'utm_source',
'utm_medium',
'utm_campaign',
- // Used by experiments
+ // Experiments add this key.
'feature',
- // Used to track API requests from external sources
+ // External API request links add this key.
'client_name',
])
@@ -87,8 +87,7 @@ export default function handleInvalidQuerystrings(
let keys = originalKeys.filter((key) => !RECOGNIZED_KEYS_BY_ANY.has(key))
if (keys.length > 0) {
- // Before we judge the number of query strings, strip out all the ones
- // we're familiar with.
+ // Count only keys this middleware does not recognize for the current path.
for (const [prefix, recognizedKeys] of Object.entries(RECOGNIZED_KEYS_BY_PREFIX)) {
if (path.startsWith(prefix)) {
keys = keys.filter((key) => !recognizedKeys.includes(key))
@@ -96,9 +95,7 @@ export default function handleInvalidQuerystrings(
}
}
- // If you fill out the Survey form with all the fields and somehow
- // don't attempt to make a POST request, you'll end up with a query
- // string like this.
+ // GET and HEAD with hidden survey-token plus real survey-vote match this honeypot branch.
const honeypotted = 'survey-token' in query && 'survey-vote' in query
if (keys.length >= MAX_UNFAMILIAR_KEYS_BAD_REQUEST || honeypotted) {
@@ -118,21 +115,12 @@ export default function handleInvalidQuerystrings(
return
}
- // This is a pattern we've observed in production and we're shielding
- // against it happening again. The root home page is hit with a
- // 8 character long query string that has no value.
+ // Production has sent the home page 8-character valueless query strings.
const rootHomePage = path.split('/').length === 2
const badKeylessQuery =
rootHomePage && keys.length === 1 && keys[0].length === 8 && !query[keys[0]]
- // It's still a mystery why these requests happen but we've seen large
- // number of requests that have a very long URL-encoded query string
- // that starts with 'tool' but doesn't have any value.
- // For example
- // ?tool%25252525253Dvisualstudio%252525253D%2525252526tool%25252525...
- // ...3Dvscode%2525253D%25252526tool%2525253Dvscode%25253D%252526tool...
- // ...%25253Dvimneovim%253D%2526tool%253Djetbrains%3D%26tool%3Djetbrains=&
- // Let's shield against those by removing them.
+ // Strip production keys like tool%25252525253Dvisualstudio...%26tool%3Djetbrains=.
const badToolsQuery = keys.some((key) => key.startsWith('tool%') && !query[key])
if (keys.length >= MAX_UNFAMILIAR_KEYS_REDIRECT || badKeylessQuery || badToolsQuery) {
diff --git a/src/shielding/middleware/handle-malformed-urls.ts b/src/shielding/middleware/handle-malformed-urls.ts
index a5e364b9543b..cb4ec93d66fe 100644
--- a/src/shielding/middleware/handle-malformed-urls.ts
+++ b/src/shielding/middleware/handle-malformed-urls.ts
@@ -3,11 +3,8 @@ import type { Response, NextFunction } from 'express'
import { defaultCacheControl } from '@/frame/middleware/cache-control'
import { ExtendedRequest } from '@/types'
-/**
- * Malformed UTF-8 in a URL, like `%FF`, makes decodeURIComponent throw.
- * Express does not catch that while parsing, so without this the crash
- * happens later at the router level.
- */
+// Malformed UTF-8 in a URL, such as %FF, makes decodeURIComponent throw.
+// Express does not catch that while parsing, so catch it before the router runs.
export default function handleMalformedUrls(
req: ExtendedRequest,
res: Response,
diff --git a/src/shielding/middleware/handle-old-next-data-paths.ts b/src/shielding/middleware/handle-old-next-data-paths.ts
index ac47f1883cbe..9d276ebac1e9 100644
--- a/src/shielding/middleware/handle-old-next-data-paths.ts
+++ b/src/shielding/middleware/handle-old-next-data-paths.ts
@@ -1,24 +1,9 @@
-/**
- * This middleware looks at the URL if it's something like:
- *
- * /_next/data/oOIffMZgfjR6sR9pa50O9/en/free-pro-team%40latest/pages.json?...
- *
- * And from that, it compares that oOIffMZgfjR6sR9pa50O9 with the content
- * of the .next/BUILD_ID file. If they don't match, then it's going to 404.
- * But instead of letting the nextApp.render404() handle it, we're going to
- * manually handle it here.
- * This makes sure the response is a short and fast plain text 404 response.
- * And we can force it to be served with a cache-control which allows
- * the CDN to cache it a bit.
- *
- * Note that when you start the local server with `npm run dev` and
- * do client-side navigation in the app, NextJS will send XHR requests for...
- *
- * /_next/data/development/en/free-pro-team%40latest/pages.json?...
- *
- * Relying on that test is easier than to try to parse the
- * value of `process.env.NODE_ENV`.
- */
+// Next.js data routes include a build ID, for example:
+// /_next/data/oOIffMZgfjR6sR9pa50O9/en/free-pro-team%40latest/pages.json
+// When the build ID does not match .next/BUILD_ID, return a short cacheable 404
+// here instead of letting nextApp.render404 handle it.
+// Local npm run dev uses /_next/data/development/..., so that path stays unblocked
+// without depending on NODE_ENV parsing.
import fs from 'fs'
diff --git a/src/shielding/tests/invalid-querystring-values.ts b/src/shielding/tests/invalid-querystring-values.ts
index 985c6993f546..4b5e7d5f38b9 100644
--- a/src/shielding/tests/invalid-querystring-values.ts
+++ b/src/shielding/tests/invalid-querystring-values.ts
@@ -8,14 +8,11 @@ describe('invalid query string values', () => {
if (key === 'platform') value = 'mac'
else if (key === 'tool') value = 'curl'
else throw new Error('unknown key')
-
- // Valid value
{
const url = `/en/pages?${key}=${value}`
const res = await get(url)
expect(res.statusCode).toBe(200)
}
- // Invalid value
{
const url = `/en/pages?${key}=JUNK&other=thing`
const res = await get(url)
diff --git a/src/shielding/tests/invalid-querystrings.ts b/src/shielding/tests/invalid-querystrings.ts
index 23871850c62e..b00a97578b33 100644
--- a/src/shielding/tests/invalid-querystrings.ts
+++ b/src/shielding/tests/invalid-querystrings.ts
@@ -12,8 +12,7 @@ const alphabet = alpha.map((x) => String.fromCharCode(x))
describe('invalid query strings', () => {
test('400 for too many unrecognized query strings', async () => {
- // This test depends on knowing exactly the number
- // of unrecognized query strings that will trigger a 400.
+ // The exported threshold keeps this test tied to the middleware limit.
const sp = new URLSearchParams()
for (const letter of alphabet.slice(0, MAX_UNFAMILIAR_KEYS_BAD_REQUEST)) {
sp.set(letter, '1')
@@ -27,8 +26,7 @@ describe('invalid query strings', () => {
})
test('302 redirect for many unrecognized query strings', async () => {
- // This test depends on knowing exactly the number
- // of unrecognized query strings that will trigger a redirect.
+ // The exported threshold keeps this test tied to the middleware limit.
const sp = new URLSearchParams()
for (const letter of alphabet.slice(0, MAX_UNFAMILIAR_KEYS_REDIRECT)) {
sp.set(letter, '1')
@@ -58,7 +56,7 @@ describe('invalid query strings', () => {
const res = await get(url)
expect(res.statusCode).toBe(302)
expect(res.headers.location).toBe('/en')
- // But note that it only applies to the home page!
+ // The 8-character rule applies to root-level paths.
{
const nestedUrl = `/en/get-started?${randomCharacters(8)}`
const nestedRes = await get(nestedUrl)
@@ -72,7 +70,7 @@ describe('invalid query strings', () => {
expect(res.statusCode).toBe(400)
expect(res.headers['content-type']).toMatch('text/plain')
expect(res.body).toMatch('Invalid query string')
- // Must not reflect the user-supplied key name
+ // Do not reflect the user-supplied key name.
expect(res.body).not.toContain('(query)')
})
@@ -82,7 +80,7 @@ describe('invalid query strings', () => {
expect(res.statusCode).toBe(400)
expect(res.headers['content-type']).toMatch('text/plain')
expect(res.body).toMatch('Invalid query string')
- // Must not reflect the user-supplied key name
+ // Do not reflect the user-supplied key name.
expect(res.body).not.toContain('(constructor)')
})
@@ -102,11 +100,9 @@ describe('invalid query strings', () => {
expect(res.body).not.toContain('alert')
})
+ // Bug bounty proof of concept: enough unrecognized query keys force a redirect.
+ // safeRedirect normalizes // to / so Location cannot become protocol-relative.
test('redirect from unrecognized query strings does not produce open redirect', async () => {
- // This is the exact PoC from the bug bounty report.
- // With enough unrecognized query keys, the middleware redirects
- // using req.path. res.safeRedirect normalizes // to / so the
- // Location header can never be a protocol-relative URL.
const res = await get('//evil.com?a=1&b=2&c=3')
expect(res.headers.location).not.toMatch(/^\/\//)
})
diff --git a/src/shielding/tests/malformed-urls.ts b/src/shielding/tests/malformed-urls.ts
index 2777e90d6c9f..6219095fdc0a 100644
--- a/src/shielding/tests/malformed-urls.ts
+++ b/src/shielding/tests/malformed-urls.ts
@@ -34,7 +34,8 @@ describe('malformed URLs', () => {
test('allows URLs with control characters (valid UTF-8)', async () => {
// %01 decodes fine, so the middleware lets it through.
const res = await get('/en/test-%01-page')
- expect(res.statusCode).toBe(404) // 404 because the page does not exist, not 400
+ // The page does not exist, so a valid URL returns 404 instead of 400.
+ expect(res.statusCode).toBe(404)
})
test('allows valid URLs with proper encoding', async () => {
@@ -48,7 +49,7 @@ describe('malformed URLs', () => {
})
test('blocks malformed query parameters', async () => {
- // This is caught by checking originalUrl which contains the raw, unparsed URL
+ // originalUrl keeps the raw, unparsed query string.
const res = await get('/en/search?q=test%FF')
expect(res.statusCode).toBe(400)
expect(res.headers['content-type']).toMatch('text/plain')
diff --git a/src/shielding/tests/shielding.ts b/src/shielding/tests/shielding.ts
index dd81e2ebce0d..43d297158c67 100644
--- a/src/shielding/tests/shielding.ts
+++ b/src/shielding/tests/shielding.ts
@@ -30,8 +30,7 @@ describe('junk paths', () => {
test('double-slash with query params does not open redirect', async () => {
const res = await get('//evil.com?a=1&b=2&c=3')
- // With 3 unrecognized query keys, the query string middleware redirects
- // using res.safeRedirect which normalizes // to /
+ // With 3 unrecognized query keys, safeRedirect normalizes // to /.
expect(res.headers.location).not.toMatch(/^\/\//)
})
@@ -96,7 +95,7 @@ describe('index.md and .md suffixes', () => {
// .md is stripped and request flows through with Accept: text/markdown
{
const res = await get('/en/get-started.md')
- // Should not redirect — serves markdown directly (or 404 if page doesn't exist)
+ // Serves markdown directly or returns 404 when the page does not exist.
expect(res.statusCode).not.toBe(301)
expect(res.statusCode).not.toBe(302)
}
diff --git a/src/tests/helpers/caching-headers.ts b/src/tests/helpers/caching-headers.ts
index a8fc1bcf7fd1..4b9f201d18ff 100644
--- a/src/tests/helpers/caching-headers.ts
+++ b/src/tests/helpers/caching-headers.ts
@@ -22,15 +22,13 @@ export function checkCachingHeaders(
}
const maxAgeSeconds = parseInt(maxAgeMatch[1], 10)
- // Let's not be too specific in the tests, just as long as it's testing
- // that it's a reasonably large number of seconds.
+ // Use a lower bound so tests tolerate normal cache-window changes.
expect(maxAgeSeconds).toBeGreaterThanOrEqual(minMaxAge)
const surrogateKeyHeader = res.headers['surrogate-key'] as string
const firstToken = surrogateKeyHeader.split(/\s/g)[0]
if (defaultSurrogateKey) {
- // Default cacheable responses are keyed by language for the staggered,
- // per-language deploy purge: either `no-language` or `language:<code>`.
+ // Per-language purges need no-language or language:<code> as the first surrogate key.
expect(firstToken === 'no-language' || /^language:[a-z-]+$/.test(firstToken)).toBe(true)
} else {
expect(firstToken).toBe(SURROGATE_ENUMS.MANUAL)
diff --git a/src/tests/helpers/check-url.ts b/src/tests/helpers/check-url.ts
index 6f05e4f960d3..a3a19c86a21c 100644
--- a/src/tests/helpers/check-url.ts
+++ b/src/tests/helpers/check-url.ts
@@ -6,15 +6,9 @@ import type { Context } from '@/types'
const liquidStartRex = /^{%-?\s*ifversion .+?\s*%}/
const liquidEndRex = /{%-?\s*endif\s*-?%}$/
-// Return
-//
-// /foo/bar
-//
-// if the text input was
-//
-// {% ifversion ghes%}/foo/bar{%endif %}
-//
-// And if no liquid, just return as is.
+// Frontmatter link lists sometimes wrap paths in ifversion Liquid; checks need the raw path.
+// Example input: {% ifversion ghes%}/foo/bar{%endif %}
+// Output: /foo/bar
function stripLiquid(text: string): string {
if (liquidStartRex.test(text) && liquidEndRex.test(text)) {
return text.replace(liquidStartRex, '').replace(liquidEndRex, '').trim()
@@ -24,27 +18,20 @@ function stripLiquid(text: string): string {
return text
}
-// Given a URI that does not start with a specific language,
-// return undefined if it can found as a known page.
-// Otherwise, return an object with information that is used to
-// print a useful test error message in the assertion.
+// Return details for assertion errors when a language-free URI cannot resolve to a known page.
export function checkURL(uri: string, index: number, redirectsContext: Context) {
const url = `/en${stripLiquid(uri).split('#')[0]}`
if (!redirectsContext.pages || !(url in redirectsContext.pages)) {
- // Some are written without a version, but don't work with the
- // default version.
+ // Some unversioned links resolve only after redirects add a version.
let redirects = getRedirect(url, redirectsContext)
- // If it does indeed redirect to a different version,
- // strip that and compare again.
if (redirects) {
const withoutVersion = getPathWithoutVersion(redirects)
if (withoutVersion === url) {
- // That means, it's actually fine
return null
}
redirects = getPathWithoutLanguage(withoutVersion)
}
return { uri, index, redirects }
}
- return null // Falsy value will be filtered out later
+ return null
}
diff --git a/src/tests/helpers/data-directory.ts b/src/tests/helpers/data-directory.ts
index a61d332a6271..a39240d69afa 100644
--- a/src/tests/helpers/data-directory.ts
+++ b/src/tests/helpers/data-directory.ts
@@ -8,42 +8,12 @@ interface DataStructure {
[key: string]: string | DataStructure
}
-// This helper class exists so you can create a temporary root directory
-// full of data files.
-// For example, if you want to unit test with files that are not part
-// of the git repo but should only "temporarily" exist for the duration
-// of the tests.
-// This class takes an object and generates that as files on disk. E.g.
-//
-// const dataDirectory = new DataDirectory({
-// data: {
-// reusables: {
-// example: 'a rose by any other name\nwould smell as sweet',
-// },
-// },
-// })
-// process.env.ROOT = dataDirectory.root
-// ...
-// try {
-// ...unit tests here...
-// } finally {
-// dataDirectory.destroy()
-// }
-//
-// Note that it's very specific about keys. For example, if the nested
-// object has a key called 'ui' it doesn't create a deeper nested structure
-// but takes the nested structure and writes it to a single .yml file.
-// For example:
-//
-// const dataDirectory = new DataDirectory({
-// data: {
-// ui: {
-// key: "Value",
-// deep: {
-// er: "Stuff"
-//
-// will create a single <tempdir>/data/ui.yml file.
-//
+// DataDirectory builds a temporary data root for tests that need files outside the repository.
+// It writes nested data objects to disk, then destroy removes the temp root.
+// Example: new DataDirectory({ data: { reusables: { example: 'temporary text' } } }).
+// Point ROOT at dataDirectory.root during the test, then call dataDirectory.destroy().
+// Special keys match production data conventions: ui writes data/ui.yml, variables write .yml
+// files, and reusables write .md files.
export class DataDirectory {
root: string
@@ -71,7 +41,7 @@ export class DataDirectory {
fs.writeFileSync(path.join(here, `${key}.md`), value, 'utf-8')
} else {
fs.mkdirSync(path.join(here, key))
- // Using 'as' assertion because we know value must be an object when it's not a string in reusables context
+ // The reusables branch already ruled out strings.
this.create(value as DataStructure, path.join(here, key), false, true)
}
} else if (isVariables) {
@@ -82,7 +52,7 @@ export class DataDirectory {
} else {
const there = path.join(here, key)
fs.mkdirSync(there)
- // Using 'as' assertions because nested directory values are always objects, not strings
+ // Nested directory branches only handle objects.
if (key === 'reusables') {
this.create(value as DataStructure, there, false, true)
} else if (key === 'variables') {
diff --git a/src/tests/helpers/e2etest.ts b/src/tests/helpers/e2etest.ts
index 7bd87f4b8bd5..8b4a8f7cd825 100644
--- a/src/tests/helpers/e2etest.ts
+++ b/src/tests/helpers/e2etest.ts
@@ -82,7 +82,7 @@ export async function get<T extends ResponseTypes = 'text'>(
headersRecord[key] = value
}
- // Return response in got-compatible format
+ // Tests still expect got-compatible response fields.
return {
body: responseBody,
statusCode: response.status,
@@ -116,7 +116,7 @@ export async function getDOMCached(
const $ = await getDOM(route, options)
getDOMCache.set(key, $)
}
- // The non-null assertion is safe here because we've just set the key if it didn't exist
+ // The cache sets the key before this lookup.
return getDOMCache.get(key)!
}
@@ -134,9 +134,9 @@ export async function getDOM(route: string, options: GetDOMOptions = {}): Promis
const $ = load(res.body || '', { xmlMode: true })
const result = $ as CachedDOMResult
- // Attach res to the cheerio object for backward compatibility
+ // Older tests read the response from the Cheerio object.
result.res = res
- // Attach $ to itself for destructuring compatibility
+ // Older tests destructure $ from the Cheerio object.
result.$ = result
return result
diff --git a/src/tests/helpers/schemas.ts b/src/tests/helpers/schemas.ts
index cb35e6c84319..e1896f82b772 100644
--- a/src/tests/helpers/schemas.ts
+++ b/src/tests/helpers/schemas.ts
@@ -1,35 +1,22 @@
import type { ErrorObject } from 'ajv'
-// lightly format the schema errors object returned from ajv to connect the
-// error message to where the problem is -- for example, if a top level 'date'
-// property isn't correctly formatted as a date we return:
-//
-// at 'date': must match format "date"
-//
-// if sections > features has an array of objects that must have a 'notes'
-// property and we misspell the property name in the first item:
-//
-// at 'sections > features > item 0': must have required property 'notes'
+// Format AJV errors with the path first, so data-file failures point at the bad value.
+// Example: at 'sections > features > item 0': must have required property 'notes'
export const formatAjvErrors = (errors: ErrorObject[] = []): string => {
return errors
.map((errorObj) => {
- // ajv instancePath tells us in the data we're checking where there was a
- // schema error -- for release notes looks like this for example
- // `/sections/features/0` if the error is in the first feature under sections.
+ // instancePath points to the failing data path, such as /sections/features/0.
const split = errorObj.instancePath.split('/')
split.shift()
- // handle additional properties error specifically since we can call out
- // which property shouldn't be there
+ // Call out the unexpected property name for additionalProperties errors.
let additionalProperties = ''
if (errorObj.keyword === 'additionalProperties') {
additionalProperties = `: additional property is '${errorObj.params.additionalProperty}'`
}
- // ajv's enum message is "must be equal to one of the allowed values" but
- // does not name them, which is not actionable when the schema lives in a
- // different file than the data being validated
+ // AJV omits enum values from its message, but schema-file lookups need actionable values.
let allowedValues = ''
if (errorObj.keyword === 'enum' && Array.isArray(errorObj.params.allowedValues)) {
diff --git a/src/tests/helpers/schemas/products-schema.ts b/src/tests/helpers/schemas/products-schema.ts
index 3da38b902727..4b0fb77b1fee 100644
--- a/src/tests/helpers/schemas/products-schema.ts
+++ b/src/tests/helpers/schemas/products-schema.ts
@@ -15,19 +15,19 @@ export default {
href: {
description: 'the href to the product landing page',
type: 'string',
- pattern: '^(/|http)', // if internal, must start with a slash; if external, must start with http
+ pattern: '^(/|http)', // Internal hrefs start with /; external hrefs start with http.
},
dir: {
description: 'the local relative path to the product directory',
type: 'string',
- pattern: '^content/.*?[^/]$', // must start with content, can't end with a slash
+ pattern: '^content/.*?[^/]$', // Product directories start with content and omit a trailing slash.
},
toc: {
description: 'the local relative path to the product toc page',
type: 'string',
- pattern: '^content/.*?index.md$', // must start with content and end with index.md
+ pattern: '^content/.*?index.md$', // TOC files start with content and end with index.md.
},
hasEnterpriseUserVersions: {
diff --git a/src/tests/helpers/schemas/versions-schema.ts b/src/tests/helpers/schemas/versions-schema.ts
index 44b84bf50ce6..e76431d37d86 100644
--- a/src/tests/helpers/schemas/versions-schema.ts
+++ b/src/tests/helpers/schemas/versions-schema.ts
@@ -1,5 +1,4 @@
-// match plan@release
-// e.g., free-pro-team@latest, enterprise-server@3.0
+// Version strings match plan@release, for example free-pro-team@latest or enterprise-server@3.XX.
const planPattern = '^[a-z-]+'
const releasePattern = '[a-z0-9-.]+'
const delimiter = '@'
@@ -63,7 +62,7 @@ const schema: VersionSchema = {
pattern: planPattern,
},
planTitle: {
- description: 'the plan title', // this is the same as the version title, sans numbered release
+ description: 'the plan title', // planTitle matches versionTitle without the numbered release.
type: 'string',
},
shortName: {
@@ -90,7 +89,8 @@ const schema: VersionSchema = {
type: 'boolean',
},
nonEnterpriseDefault: {
- description: 'boolean indicating whether the plan is the default non-Enterprise version', // helper if the plan name changes
+ // Identifies the default non-Enterprise version without hard-coding a plan name.
+ description: 'boolean indicating whether the plan is the default non-Enterprise version',
type: 'boolean',
},
openApiBaseName: {
diff --git a/src/tests/lib/validate-json-schema.ts b/src/tests/lib/validate-json-schema.ts
index b20418628e60..76c8efa913ef 100644
--- a/src/tests/lib/validate-json-schema.ts
+++ b/src/tests/lib/validate-json-schema.ts
@@ -10,12 +10,8 @@ addErrors(ajv)
ajv.addKeyword({
keyword: 'translatable',
})
-// Schemas can contain the custom keyword `lintable` to define
-// a property as a Markdown string that can be linted by the
-// content linter.
-// The custom keyword does not define a custom validator function.
-// This allows the custom keyword to be present in a schema but
-// doesn't perform additional validation other than type checking.
+// The lintable keyword marks Markdown strings that the content linter can check.
+// AJV still validates only the string type.
ajv.addKeyword({
keyword: 'lintable',
type: 'string',
@@ -25,21 +21,13 @@ ajv.addFormat('semver', {
validate: (x: string): boolean => semver.validRange(x) !== null,
})
-// The ajv.validate function is supposed to cache
-// the compiled schema, but the documentation says
-// that the best performance is achieved by calling
-// the compile function and then calling validate.
-// So when the same schema is validated multiple times,
-// this is the best function to use. If the schema
-// changes from one call to the next, then the validateJson
-// function makes more sense to use.
+// Reuse compiled validators when one schema validates multiple payloads.
+// Use validateJson when each call may receive a different schema.
export function getJsonValidator(schema: SchemaObject): ValidateFunction {
return ajv.compile(schema)
}
-// The next call to ajv.validate will overwrite
-// the ajv.errors property, so returning it here
-// ensures that it remains accessible.
+// Clone AJV errors before the next validate call overwrites ajv.errors.
export function validateJson(
schema: SchemaObject,
data: unknown,
diff --git a/src/tests/mocks/cse-copilot-mock.ts b/src/tests/mocks/cse-copilot-mock.ts
index 6e1d0e8b6094..dbfd0d51fb1a 100644
--- a/src/tests/mocks/cse-copilot-mock.ts
+++ b/src/tests/mocks/cse-copilot-mock.ts
@@ -1,6 +1,6 @@
import { Request, Response } from 'express'
-// Prefix used for mocking. This can be any value
+// Tests use this prefix only to mount the mock route; any stable value works.
export const CSE_COPILOT_PREFIX = 'cse-copilot'
export function cseCopilotPostAnswersMock(req: Request, res: Response) {
diff --git a/src/tests/mocks/start-mock-server.ts b/src/tests/mocks/start-mock-server.ts
index 9236b73a60e6..b3a82d05c9e0 100644
--- a/src/tests/mocks/start-mock-server.ts
+++ b/src/tests/mocks/start-mock-server.ts
@@ -1,24 +1,7 @@
-/* When testing API routes via an integration test, e.g.
-
-const res = await post('/api/<some-route>', {
- body: JSON.stringify(api_body),
- headers: { 'Content-Type': 'application/json' },
-})
-
-expect(res.status).toBe(200)
-
-The `api/<route>` may call an external URL.
-
-We are unable to use `nock` in this circumstance since we run the server in a separate instance.
-
-Instead, we can use the `startMockServer` helper to start a mock server that will intercept the request and return a canned response.
-
-In order for this to work you MUST use a process.env variable for the URL you are calling,
-
-e.g. `process.env.CSE_COPILOT_ENDPOINT`
-
-You should override the variable in the overrideEnvForTesting function in this file.
-*/
+// Integration tests cannot use nock when API routes call external URLs from a separate server.
+// Example: post to /api/<some-route>, and let that route call the mock server.
+// Point the route at this mock server through an env var such as CSE_COPILOT_ENDPOINT.
+// Set that env var in overrideEnvForTesting.
import express from 'express'
import type { Server } from 'http'
diff --git a/src/tests/scripts/copy-fixture-data.ts b/src/tests/scripts/copy-fixture-data.ts
index cc2ad6437747..dc8fc04092b3 100755
--- a/src/tests/scripts/copy-fixture-data.ts
+++ b/src/tests/scripts/copy-fixture-data.ts
@@ -1,14 +1,5 @@
-// [start-readme]
-//
-// There are certain files that have to be manually copied from the
-// real data into the test fixture data.
-//
-// This script copies the files from `data/` into `tests/fitures/data/...`
-// that are files that are both needed for fixture testing yet can't
-// live with the code. For example, `data/ui.yml` is part of the rendering
-// code, but it lives in `data/` so it can be translated.
-//
-// [end-readme]
+// Some fixture tests need translated data files that live under data, outside test code.
+// This script copies those required data files into src/fixtures/fixtures/data.
import fs from 'fs'
import path from 'path'
@@ -16,8 +7,7 @@ import path from 'path'
import { program } from 'commander'
import chalk from 'chalk'
-// Here, write down all the files that are actually part of the rendering
-// functionality yet live in data.
+// Keep files that rendering needs but stores under data.
const MANDATORY_FILES = [
'data/ui.yml',
'data/reusables/enterprise_deprecation/deprecation_details.md',
diff --git a/src/tests/scripts/copy-to-test-repo.sh b/src/tests/scripts/copy-to-test-repo.sh
index f82f54f0349f..03f8ce9df386 100755
--- a/src/tests/scripts/copy-to-test-repo.sh
+++ b/src/tests/scripts/copy-to-test-repo.sh
@@ -1,7 +1,7 @@
#!/bin/bash
-# Copies certain directories over to docs-internal-test and pushes. Useful for debugging actions
-# Doesn't copy over content/ and data/ directories
+# Copies selected files to docs-internal-test and pushes them for GitHub Actions debugging.
+# Excludes content, data, node_modules, Git metadata, .gitattributes, and .github/CODEOWNERS.
echo "Make sure to run this script in the root path of docs-internal!"
@@ -39,5 +39,3 @@ fi;
exit
-
-
diff --git a/src/tools/components/Fields.tsx b/src/tools/components/Fields.tsx
index 635446920d10..7e0fcf9d9593 100644
--- a/src/tools/components/Fields.tsx
+++ b/src/tools/components/Fields.tsx
@@ -30,11 +30,7 @@ export const Fields = (fieldProps: {
if (onSelect) onSelect(item)
setOpen(!open)
}}
- // These extra links in the pickers are not a part of the selection variant
- // in that they are generally external links, so we want to remove the selection
- // variant span box in front of it. To date there isn't a possibility to have
- // an ActionMenu in Primer that allow non-selection variant items with selection
- // variant items
+ // Primer ActionMenu cannot mix selection items with external links, so extras hide the indicator.
className={cx(
(item.extra?.arrow || item.extra?.info) && styles.extrasDisplay,
styles.linkItem,
diff --git a/src/tools/components/InArticlePicker.module.scss b/src/tools/components/InArticlePicker.module.scss
index 47edd48cfd44..072817233a7b 100644
--- a/src/tools/components/InArticlePicker.module.scss
+++ b/src/tools/components/InArticlePicker.module.scss
@@ -1,11 +1,9 @@
.container {
- // Override Primer's selected tab indicator color to meet WCAG 1.4.11
- // non-text contrast minimum of 3:1. The default --color-primer-border-active
- // (#FD8C73) has only 2.3:1 contrast. Using a Primer theme variable
- // that meets contrast in both light and dark color modes.
+ // Primer's --color-primer-border-active has 2.3:1 contrast and fails WCAG 1.4.11.
+ // --color-severe-emphasis meets the 3:1 minimum in light and dark modes.
--underlineNav-borderColor-active: var(--color-severe-emphasis);
- // target the ActionList dropdown that appears when UnderlineNav overflows
+ // Primer does not expose a stable class for the UnderlineNav overflow ActionList.
ul[class*="prc-ActionList-ActionList"] {
background-color: var(
--overlay-bgColor,
diff --git a/src/tools/components/InArticlePicker.tsx b/src/tools/components/InArticlePicker.tsx
index f8c9dbe52973..0b726836f1c9 100644
--- a/src/tools/components/InArticlePicker.tsx
+++ b/src/tools/components/InArticlePicker.tsx
@@ -14,9 +14,9 @@ type Option = {
label: string
}
type Props = {
- // Use this if not specified on the query string
+ // Used when the query string does not specify a valid value.
defaultValue?: string
- // Use this if not specified on the query string or no cookie
+ // Used when the query string is invalid, defaultValue is unset, and the cookie is invalid.
fallbackValue: string
cookieKey: string
queryStringKey: string
@@ -39,12 +39,9 @@ export const InArticlePicker = ({
const { query, locale } = router
const [currentValue, setCurrentValue] = useState('')
- // Tracks whether the last currentValue change was triggered by a user click
- // (as opposed to initial mount or external navigation). When true, we move
- // focus to the newly-selected tab so keyboard users don't lose their place.
+ // True after user clicks, so focus moves only for direct tab selection.
const focusAfterNavRef = useRef(false)
- // Run on mount for client-side only features
useEffect(() => {
const raw = query[queryStringKey]
let value = ''
@@ -52,8 +49,7 @@ export const InArticlePicker = ({
if (Array.isArray(raw)) value = raw[0]
else value = raw
}
- // Only pick it up from the possible query string if its value
- // is a valid option.
+ // Ignore query string values outside this picker's options.
const possibleValues = options.map((option) => option.value)
if (!value || !possibleValues.includes(value)) {
const cookieValue = Cookies.get(cookieKey)
@@ -70,49 +66,24 @@ export const InArticlePicker = ({
const [asPathRoot, asPathQuery = ''] = router.asPath.split('#')[0].split('?')
- // Use a layout effect so the DOM mutation (hiding non-matching .ghd-tool
- // content) happens before the browser paints. With React 19's stricter
- // effect timing, a regular useEffect could leave non-matching content
- // visible on initial page load until after first paint.
+ // Apply the selection before paint so non-matching .ghd-tool content does not flash.
useIsomorphicLayoutEffect(() => {
- // This will make the hook run this callback on mount and on change.
- // That's important because even though the user hasn't interacted
- // and made an overriding choice, we still want to run this callback
- // because the page might need to be corrected based on *a* choice
- // independent of whether it's a change.
+ // Initial values still need to update the page before the user interacts.
if (currentValue) {
onValue(currentValue)
}
}, [
currentValue,
- // This is important because we can't otherwise rely on the firing
- // of this effect on initial mount. It also needs to fire when the
- // URL (i.e. route) changes.
- // Don't use `router.asPath` because that contains the query string
- // which we handle in the other useEffect above.
+ // Query string changes are handled separately, so depend on the route path only.
asPathRoot,
])
- // This is exclusively for local development.
- // If you're in local development, you have the <ClientSideRefresh>
- // causing a XHR refresh of the content triggered by the Page Visibility
- // API (implemented in the uswSWR hook). That means that on the pages that
- // contain these `.ghd-tool` classes, any DOM changes we might
- // have previously made are lost and started over.
+ // Local ClientSideRefresh replaces article HTML on visibility changes, so reapply selection.
useEffect(() => {
let mounted = true
const toggleVisibility = () => {
if (document.visibilityState === 'visible') {
- // We don't need to track this timer, and possibly cancel it on
- // dismount, because within the callback we use the `mounted`
- // boolean which means we can know to do nothing if the parent
- // component has been dismounted.
- // The reason this is wrapped in a short timeout is because the
- // React rendering might not actually have fully updated the DOM
- // (from the XHR HTML it receives) so allow the DOM to refresh
- // first before asking it to change. The number can be quite low
- // (which is sufficient for human eyes) but must be at least
- // in the lower hundreds of milliseconds.
+ // Keep at least a 100 ms delay so refreshed HTML reaches the DOM before selection changes it.
setTimeout(() => {
if (mounted) {
onValue(currentValue)
@@ -148,10 +119,7 @@ export const InArticlePicker = ({
Cookies.set(cookieKey, value)
}
- // After a user clicks a tab, the shallow route change updates `currentValue`.
- // Once the DOM reflects the new selection (aria-current="page" is on the new
- // tab), move keyboard focus there so the user's context is preserved.
- // WCAG 2.4.3 Focus Order: focus must land on the triggered control.
+ // WCAG 2.4.3 requires focus to remain on the triggered tab after shallow routing.
useEffect(() => {
if (!focusAfterNavRef.current || !currentValue) return
focusAfterNavRef.current = false
@@ -171,7 +139,7 @@ export const InArticlePicker = ({
return (
<div data-testid={`${queryStringKey}-picker`} className={styles.container}>
- {/* The key attribute is required for a bug in UnderlineNav that doesn't render the component when there are changes to the items. */}
+ {/* UnderlineNav can miss item changes without a changing key. */}
<UnderlineNav key={router.asPath} {...sharedContainerProps}>
{options.map((option) => {
params.set(queryStringKey, option.value)
diff --git a/src/tools/components/PlatformPicker.tsx b/src/tools/components/PlatformPicker.tsx
index 7d78b2e48e6c..e113fdd96003 100644
--- a/src/tools/components/PlatformPicker.tsx
+++ b/src/tools/components/PlatformPicker.tsx
@@ -13,7 +13,7 @@ const platforms = [
{ value: 'linux', label: 'Linux' },
]
-// Note: platform === os
+// Content calls this preference platform, but the stored preference name is os.
export const PlatformPicker = () => {
const { defaultPlatform, detectedPlatforms } = useArticleContext()
@@ -28,9 +28,7 @@ export const PlatformPicker = () => {
setDefaultUA(userAgent)
}, [])
- // Defensively, just in case some article happens to have an array
- // but for some reasons, it might be empty, let's not have a picker
- // at all.
+ // Articles with no detected platforms do not need a picker.
if (!detectedPlatforms.length) return null
const options = platforms.filter((platform) => detectedPlatforms.includes(platform.value))
@@ -46,9 +44,7 @@ export const PlatformPicker = () => {
cookieKey={OS_PREFERRED_COOKIE_NAME}
queryStringKey={platformQueryKey}
onValue={(value: string) => {
- // Visibility is driven by React state via ToggleableContent/MiniTocs
- // (#6619); the article body is React-owned on both the hast and string
- // paths, so no imperative DOM mutation is needed.
+ // React state drives visibility because the article body is React-owned.
setPlatform(value)
}}
preferenceName="os"
diff --git a/src/tools/components/SelectionContext.tsx b/src/tools/components/SelectionContext.tsx
index 0c09457855b6..5032ab8d1477 100644
--- a/src/tools/components/SelectionContext.tsx
+++ b/src/tools/components/SelectionContext.tsx
@@ -4,17 +4,10 @@ import type { ReactNode } from 'react'
import { allPlatforms } from '@/tools/lib/all-platforms'
import { allTools } from '@/tools/lib/all-tools'
-// React-native replacement for the imperative platform/tool visibility toggling
-// that PlatformPicker/ToolPicker used to do by walking the DOM and setting
-// `style.display` on `.ghd-tool`/`.platform-*`/`.tool-*` elements (#6619). The
-// selected platform + tool live in this context; the article body (rendered from
-// hast) maps the relevant elements to <ToggleableContent>, which reads the
-// selection and hides non-matching content instead of mutating React-owned nodes.
-//
-// Selections start empty so that the server render and the first client render
-// both show ALL variants (matching the pre-JS markup), which keeps hydration
-// stable. The pickers set the real selection in an effect after hydration, the
-// same moment the old imperative code used to run.
+// PlatformPicker and ToolPicker store selection here so ToggleableContent can
+// hide React-owned article elements without imperative style.display mutations.
+// Empty initial selections keep server and first client renders showing all variants,
+// which matches pre-JS markup and keeps hydration stable.
export type SelectionContextT = {
platform: string
@@ -62,14 +55,10 @@ function toClassList(className: unknown): string[] {
return []
}
-// Determine whether an element is platform/tool-scoped and which value gates it.
-// `.ghd-tool <value>` is a block (the {% mac %}/{% webui %} liquid tags); the
-// extra class is the platform or tool value. `platform-<value>`/`tool-<value>`
-// are author-written inline spans. We classify strictly against the canonical
-// platform/tool vocabularies and return null on anything outside them, so an
-// unrecognized class never makes content disappear. When several recognized
-// markers are present the first match wins; in practice an element carries
-// exactly one platform/tool marker.
+// .ghd-tool uses a separate class for the platform or tool value.
+// platform-<value> and tool-<value> are author-written inline spans.
+// Strict vocabulary checks prevent unknown classes from hiding content.
+// .ghd-tool prefers a recognized platform; inline spans use the first recognized marker.
export function classifyToggleClass(className: unknown): ToggleClassification | null {
const classes = toClassList(className)
if (!classes.length) return null
@@ -100,8 +89,7 @@ export function isToggleClass(className: unknown): boolean {
return classifyToggleClass(className) !== null
}
-// Visible when no selection has been made yet (initial render shows everything,
-// matching the pre-JS markup) or when the element's value is the selected one.
+// Empty initial selections show everything, matching the pre-JS markup.
export function isContentVisible(
classification: ToggleClassification,
selection: { platform: string; tool: string },
diff --git a/src/tools/components/ToggleableContent.tsx b/src/tools/components/ToggleableContent.tsx
index c1e114897032..0659ace2a6a6 100644
--- a/src/tools/components/ToggleableContent.tsx
+++ b/src/tools/components/ToggleableContent.tsx
@@ -7,12 +7,8 @@ import {
useSelection,
} from '@/tools/components/SelectionContext'
-// Wraps a platform/tool-scoped element from the article body hast and toggles
-// its visibility from SelectionContext instead of the old imperative
-// `style.display` mutation (#6619). Renders the same element/props/children, but
-// sets `hidden` when the current platform/tool selection doesn't match. We keep
-// the node in the DOM (hidden) rather than returning null so anchors, IDs, and
-// screen-reader traversal behave like the previous `display:none` approach.
+// ToggleableContent keeps hidden article nodes in the DOM so anchors, IDs, and
+// screen-reader traversal match the previous display:none behavior.
type ToggleableContentProps = {
tag: 'div' | 'span'
className?: string
diff --git a/src/tools/components/ToolPicker.tsx b/src/tools/components/ToolPicker.tsx
index 94748f6b1523..e0565ff98f0b 100644
--- a/src/tools/components/ToolPicker.tsx
+++ b/src/tools/components/ToolPicker.tsx
@@ -3,18 +3,16 @@ import { InArticlePicker } from './InArticlePicker'
import { useSelection } from './SelectionContext'
import { TOOL_PREFERRED_COOKIE_NAME } from '@/frame/lib/constants'
-// Example page with a tool picker:
-// http://localhost:4000/en/codespaces/developing-in-codespaces/creating-a-codespace
-
-// Note: tool === application, and picker === switcher
+// Example tool picker page: /en/codespaces/developing-in-codespaces/creating-a-codespace
+// Content calls this preference tool, but the stored preference name is application.
function getDefaultTool(defaultTool: string | undefined, detectedTools: Array<string>): string {
if (defaultTool && detectedTools.includes(defaultTool)) return defaultTool
- // Default to webui if present (this is generally the case where we show UI/CLI/Desktop info)
+ // UI, CLI, and Desktop articles default to webui.
if (detectedTools.includes('webui')) return 'webui'
- // Default to cli if present (this is generally the case where we show curl/CLI info)
+ // Curl and CLI articles default to cli.
if (detectedTools.includes('cli')) return 'cli'
return detectedTools[0]
@@ -37,9 +35,7 @@ export const ToolPicker = () => {
cookieKey={TOOL_PREFERRED_COOKIE_NAME}
queryStringKey={toolQueryKey}
onValue={(value: string) => {
- // Visibility is driven by React state via ToggleableContent/MiniTocs
- // (#6619); the article body is React-owned on both the hast and string
- // paths, so no imperative DOM mutation is needed.
+ // React state drives visibility because the article body is React-owned.
setTool(value)
}}
preferenceName="application"
diff --git a/src/tools/lib/all-platforms.ts b/src/tools/lib/all-platforms.ts
index 13845752f6a4..62636fde0b0f 100644
--- a/src/tools/lib/all-platforms.ts
+++ b/src/tools/lib/all-platforms.ts
@@ -1,4 +1,3 @@
-// All platforms available for the platform picker.
export type Platform = 'mac' | 'windows' | 'linux'
export const allPlatforms: Platform[] = ['mac', 'windows', 'linux']
diff --git a/src/tools/lib/all-tools.ts b/src/tools/lib/all-tools.ts
index db932c91334c..e6dc50beebea 100644
--- a/src/tools/lib/all-tools.ts
+++ b/src/tools/lib/all-tools.ts
@@ -1,26 +1,16 @@
-// Maps each tool identifier to its display name.
export interface ToolsMapping {
[key: string]: string
}
-/*
- All the tools available for the Tool Picker
-
- Ordered by usage analytics to prioritize most-used tools in the tool switcher.
- This ensures popular tools appear before the "More" menu in the UnderlineNav component.
-
- Analytics Query (KQL):
- ```
- docs_v0_preference_event
- | where timestamp between (ago(180d) .. now())
- | where context.hostname == 'docs.github.com'
- | where abs(totimespan(context.created - timestamp)) < 1h // bot filter
- | summarize Count=count() by Name=preference_name, Value=preference_value
- | order by Count desc
- ```
-
- Data as of 2025-11-04 (180-day window)
-*/
+// Tools are ordered by usage analytics so common options appear before the More menu.
+// Retune with this Kusto Query Language (KQL):
+// docs_v0_preference_event
+// | where timestamp between (ago(180d) .. now())
+// | where context.hostname == 'docs.github.com'
+// | where abs(totimespan(context.created - timestamp)) < 1h // bot filter
+// | summarize Count=count() by Name=preference_name, Value=preference_value
+// | order by Count desc
+// The trailing comments show counts from a 180-day window ending 2025-11-04.
export const allTools: ToolsMapping = {
vscode: 'Visual Studio Code', // 310,824
jetbrains: 'JetBrains IDEs', // 306,982
diff --git a/src/tools/scripts/liquid-markdown-tables/convert.ts b/src/tools/scripts/liquid-markdown-tables/convert.ts
index eaf95e25050e..5bc6a2373a32 100644
--- a/src/tools/scripts/liquid-markdown-tables/convert.ts
+++ b/src/tools/scripts/liquid-markdown-tables/convert.ts
@@ -1,4 +1,4 @@
-// See the comment at the top of index.ts for how to use this script.
+// Run with npm run liquid-markdown-tables -- convert content/path/to/article.md.
import fs from 'fs'
import chalk from 'chalk'
diff --git a/src/tools/scripts/liquid-markdown-tables/index.ts b/src/tools/scripts/liquid-markdown-tables/index.ts
index 04b093a4125b..7c4883a45953 100644
--- a/src/tools/scripts/liquid-markdown-tables/index.ts
+++ b/src/tools/scripts/liquid-markdown-tables/index.ts
@@ -1,47 +1,13 @@
-/**
- * This script helps you rewrite Markdown files that might contain
- * tables with Liquid `ifversion` tags the old/wrong way.
- * For example:
- *
- * | Header | Header 2 |
- * |--------|----------|
- * | bla | bla |{% ifversion dependency-review-action-licenses %}
- * | foo | foo |{% endif %}{% ifversion dependency-review-action-fail-on-scopes %}
- * | bar | bar |{% endif %}
- * | baz | baz |
- * {%- ifversion dependency-review-action-licenses %}
- * | qux | qux |{% endif %}
- *
- * Will become:
- *
- * | Header | Header 2 |
- * |--------|----------|
- * | bla | bla |
- * | {% ifversion dependency-review-action-licenses %} |
- * | foo | foo |
- * | {% endif %} |
- * | {% ifversion dependency-review-action-fail-on-scopes %} |
- * | bar | bar |
- * | {% endif %} |
- * | baz | baz |
- * | {% ifversion dependency-review-action-licenses %} |
- * | qux | qux |
- * | {% endif %} |
- *
- * Run the script like this:
- *
- * npm run liquid-markdown-tables -- convert content/path/to/article.md
- * git diff
- *
- * To *find* files that you *can* convert, use:
- *
- * npm run liquid-markdown-tables -- find
- * # or
- * npm run liquid-markdown-tables -- find --filter content/mydocset
- *
- * This will print out paths to files that most likely contain the old/wrong Liquid `ifversion` tags.
- *
- */
+// Finds and converts Markdown tables that place Liquid ifversion tags inside table rows.
+// Example input: | foo | bar |{% ifversion dependency-review-action-licenses %}
+// Example output:
+// | foo | bar |
+// | {% ifversion dependency-review-action-licenses %} |
+// Run convert: npm run liquid-markdown-tables -- convert content/path/to/article.md
+// Then run git diff to inspect changes.
+// Run find: npm run liquid-markdown-tables -- find
+// Run filtered find: npm run liquid-markdown-tables -- find --filter content/mydocset
+// Find prints paths that likely contain misplaced Liquid ifversion tags.
import { program } from 'commander'
diff --git a/src/tools/scripts/liquid-markdown-tables/lib.ts b/src/tools/scripts/liquid-markdown-tables/lib.ts
index ec15b03812d0..d98ace258ef6 100644
--- a/src/tools/scripts/liquid-markdown-tables/lib.ts
+++ b/src/tools/scripts/liquid-markdown-tables/lib.ts
@@ -1,7 +1,7 @@
-// E.g. `{%- ifversion dependency-review-action-licenses %}\n`
+// Matches a standalone ifversion line, such as {%- ifversion dependency-review-action-licenses %}.
const ifVersionRegex = /^{%-?\s*ifversion\s+([\w- ]+)\s*-?%}\n/
const ifVersionEndRegex = /\|({%-?\s*ifversion\s+([\w- ]+)\s*-?%})\n/
-// E.g. `... |{% endif %}{% ifversion dependency-review-action-fail-on-scopes %}\n`
+// Matches a row ending in endif plus ifversion, such as |{% endif %}{% ifversion foo %}.
const endifIfVersionRegex = /\|({%-?\s*endif\s*%})({%-?\sifversion\s+([\w- ]+)\s*-?%})\n/
const endifRegex = /\|({%-?\s*endif\s*%})\n/
const endifAloneRegex = /^({%-?\s*endif\s*%})\n/
@@ -40,7 +40,7 @@ export async function processFile(content: string) {
inTable = false
}
if (inTable) {
- // E.g. `{%- ifversion dependency-review-action-licenses %}\n`
+ // Standalone ifversion tags become their own table rows.
if (ifVersionRegex.test(line)) {
const better = line.replace('{%-', '{%').replace('-%}', '%}').trim()
line = `| ${better} |\n`
diff --git a/src/types/eslint-plugins.d.ts b/src/types/eslint-plugins.d.ts
index 9c948f7ae537..9b6879007196 100644
--- a/src/types/eslint-plugins.d.ts
+++ b/src/types/eslint-plugins.d.ts
@@ -1,4 +1,4 @@
-// Type declarations for ESLint plugins without official TypeScript definitions
+// These ESLint plugins do not ship TypeScript definitions.
declare module 'eslint-plugin-github' {
import type { ESLint, Linter } from 'eslint'
diff --git a/src/types/index.ts b/src/types/index.ts
index ad447b150f48..742f7ff3ffa2 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -1,2 +1,2 @@
-// Kept so existing `@/types` imports keep working.
+// Keep this barrel so existing @/types imports keep working.
export * from './types'
diff --git a/src/types/primer__octicons.d.ts b/src/types/primer__octicons.d.ts
index d5f2a11788a9..a829595b712e 100644
--- a/src/types/primer__octicons.d.ts
+++ b/src/types/primer__octicons.d.ts
@@ -28,7 +28,7 @@ declare module '@primer/octicons' {
const octicons: {
[iconName: string]: Octicon
- // Common icons (non-exhaustive list for better autocomplete)
+ // This non-exhaustive list improves autocomplete for common icons.
alert: Octicon
check: Octicon
'check-circle': Octicon
diff --git a/src/types/types.ts b/src/types/types.ts
index f7553da5a49e..0b1ff39d964d 100644
--- a/src/types/types.ts
+++ b/src/types/types.ts
@@ -16,8 +16,7 @@ export interface ResolvedArticle {
category: string[]
}
-// Middleware attaches things to the Request, like `req.context`.
-// This type collects everything we add.
+// ExtendedRequest collects properties middleware attaches to Request, including req.context.
export type ExtendedRequest = Request & {
pagePath?: string
context?: Context
@@ -27,9 +26,9 @@ export type ExtendedRequest = Request & {
FailBot?: Failbot
}
-// Hand-maintained to match `schema` in frame/lib/frontmatter.ts.
-// Generating it from the AJV schema would need extra build tooling,
-// and the schema is built dynamically with version-specific properties.
+// Hand-maintained to match schema in frame/lib/frontmatter.ts.
+// Generating it from the AJV schema would need extra build tooling because
+// the schema is built dynamically with version-specific properties.
export type PageFrontmatter = {
title: string
versions: FrontmatterVersions
@@ -112,7 +111,7 @@ type Redirects = {
}
export type Context = {
- // Allows dynamic properties like features & version shortnames as keys
+ // Context allows dynamic keys for features and version short names.
[key: string]: unknown
currentCategory?: string
currentJourneyTrack?: JourneyContext | null
@@ -428,8 +427,8 @@ export type AllVersions = {
[name: string]: Version
}
-// Cast `req.query` to this when building URLSearchParams.
-// Without it TypeScript reports an error that can't actually happen at runtime.
+// Cast req.query to this type when building URLSearchParams.
+// TypeScript rejects values that are safe at runtime.
export type URLSearchParamsTypes = string | string[][] | Record<string, string> | URLSearchParams
export type FeatureData = {
@@ -439,7 +438,7 @@ export type Versions = {
versions: FrontmatterVersions
}
-// For parsing .md frontmatter. Not the full set the schema allows.
+// Fields parsed from .md frontmatter; the full schema allows more fields.
export type MarkdownFrontmatter = {
title: string
shortTitle?: string
) elements
-// are given extra margin-top so as to divide the article into sections
-// with some extra whitespace. That's fine, but we don't to start the
-// top of the page with too much whitespace. That's why @primer/css
-// has a solution for that. Just the problem that it fails then first
-// element isn't actually a heading.
-// Note we're also doing it for a possible being the first element.
+// Primer's markdown-body first-child reset can hit a hidden first child instead
+// of the first h2 or h3. Those headings carry section spacing, but the page top
+// must not start with it, so reset the first h2 or h3 directly.
// See https://github.com/primer/css/issues/2303
-// See internal issue #2368
.markdown-body {
> h2:first-of-type,
> h3:first-of-type {
@@ -23,9 +9,8 @@
}
}
-// Horizontal scroll gets flagged as an accessibility violation.
-// Updates all code examples to only allow vertical scroll, and
-// break aggressively.
+// Horizontal scroll gets flagged as an accessibility violation, so code examples wrap
+// aggressively and allow only vertical scrolling.
.markdown-body {
pre {
overflow-x: hidden;
@@ -38,97 +23,71 @@
}
}
-// Fix for permissions icon collision with bulleted lists
-// When permissions/product statements contain lists that start immediately,
-// the list bullets can visually collide with the icons in the flex layout.
-// This adds proper spacing to prevent the collision while supporting RTL languages
-// and avoiding effects on nested lists.
-// See: https://github.com/github/docs-engineering/issues/5199
+// Lists that start immediately in permissions and product statements can collide with
+// the icon in the flex layout. Inline spacing preserves right-to-left layouts and avoids
+// changing nested lists.
.permissions-statement,
.product-statement {
ul {
margin-inline-start: 0;
- padding-inline-start: 1rem; // Ensure proper spacing from icon (RTL-aware)
+ padding-inline-start: 1rem;
}
ul > li {
- margin-inline-start: 0.5rem; // Additional spacing to prevent bullet collision (direct children only)
+ margin-inline-start: 0.5rem;
}
}
-// A CTA button written on its own line in markdown — `` — becomes its own , and that paragraph already carries the 16px
-// rhythm margin. The `mt-3` utility then stacks a second 16px inside it, so the
-// button ends up 32px below the preceding line but only 16px above the next one.
-// Drop the utility when the button is alone in its paragraph and let the
-// paragraph margin do the spacing, which puts the CTA on the same rhythm as
-// every other block. `!important` is required because Primer's spacing
-// utilities are themselves !important.
-//
-// `:only-child` is doing real work here — it is what keeps the two cases apart:
-// - CTA callouts (`product:`/`permissions:` frontmatter) put the button after
-// a
INSIDE the prose paragraph, so there is no paragraph margin above
-// it and `mt-3` is the only thing separating it from the text.
-// - The side-by-side Yes/No `.btn-outline` pairs are two buttons in one
-// paragraph.
-// Neither is an only child, so both keep their margin.
+// A CTA button written alone in markdown, such as ,
+// becomes its own p. The p already has a 16px rhythm margin, and mt-3 adds another
+// 16px, leaving 32px below the preceding line but 16px above the next one.
+// Drop mt-3 only when the button is alone in its p; Primer spacing utilities use
+// !important too.
+// :only-child keeps CTA callouts and side-by-side Yes/No buttons unchanged. Frontmatter
+// product: and permissions: put the CTA after a br inside the prose p, so mt-3 supplies
+// its only top spacing. Yes/No .btn-outline pairs have two buttons in one p.
.markdown-body p > a.btn:only-child {
margin-top: 0 !important;
}
-// @primer/css holds `.btn` at `white-space: nowrap`, which a button cannot
-// honour and still stay inside a narrow column. The longest CTA label — "Set up
-// a trial of GitHub Enterprise Cloud", 322px — is wider than the article column
-// below a ~420px viewport and wider than the callout's text column below ~390px,
-// so the button ran past the content edge and was clipped.
+// @primer/css sets .btn to white-space: nowrap, which makes long CTA labels overflow
+// narrow columns. The longest CTA label, "Set up a trial of GitHub Enterprise Cloud",
+// measures 322px, wider than the article column below about 420px and the callout text
+// column below about 390px, so it gets clipped.
//
-// Letting the label wrap fixes it with no breakpoint to guess at. An
-// inline-block is shrink-to-fit — min(max-content, available) — so
-// `white-space: normal` changes nothing until max-content exceeds the space
-// available: at every width where the button already fits it still renders on
-// one line, byte-identical. That also makes it self-correcting for longer
-// translated labels and for the narrower column a callout gives the same button.
+// Let labels wrap instead of guessing a breakpoint. inline-block shrink-to-fit,
+// min(max-content, available), means white-space: normal changes nothing until
+// max-content exceeds the available space. Buttons that fit still render on one line,
+// and longer translations or narrower callout columns self-correct.
.markdown-body a.btn,
.permissions-statement a.btn,
.product-statement a.btn {
white-space: normal;
- // Wrapping alone orphaned the trailing octicon on a line of its own: the
- // space between the label and the icon is a valid break point, and the
- // label filled the first line exactly. Laying the button out as a flex row
- // instead lets the label wrap within itself and keeps the icon beside it,
- // vertically centred. At widths where nothing wraps the result is within a
- // pixel of the inline-block it replaces: same 17px left inset, same 21px
- // right inset, same 32px height, still one line. The `gap` below covers the
- // one thing that does change.
+ // Wrapping alone can orphan the trailing octicon because the label/icon space can break.
+ // inline-flex lets the label wrap inside itself and keeps the icon beside it, centered.
+ // When nothing wraps, this stays within a pixel of inline-block: 17px left inset,
+ // 21px right inset, 32px height, and one line. The gap below covers the one change.
display: inline-flex;
align-items: center;
- // Flex layout eats the one thing that was separating the label from the icon.
- // The markup is `Label {% octicon "link-external" %}`, and that
- // literal space does survive Liquid and the markdown pipeline as a real text
- // node — but a whitespace-only text node between two flex items is not itself
- // a flex item, so no box is generated for it and the label ends up touching
- // the icon. `gap` puts the space back.
+ // Flex removes the literal space between the label and icon. In
+ // Label {% octicon "link-external" %}, Liquid and markdown preserve the
+ // space as a text node, but a whitespace-only text node between flex items creates no
+ // box, so the label touches the icon.
//
- // 4px rather than the measured width of that space glyph, because a space is
- // font- and locale-dependent — it measures differently on two machines here —
- // while 4px is the value Primer itself already uses between a button's icon
- // and its label. The button ends up a fraction of a pixel wider than it was
- // rather than most of a space narrower, on a number the design system owns.
+ // Use 4px instead of the measured space width because the space changes by font and
+ // locale. Primer already uses 4px between a button icon and label, so this
+ // design-system value makes the button slightly wider rather than most of a space narrower.
//
- // Only the label/icon gap is restored. Primer's `.btn .octicon` also carries
- // `margin-right: 4px`, which assumes a LEADING icon and so lands outside the
- // trailing icon on these CTAs, giving them 21px of inset on the right against
- // 17px on the left. That asymmetry is what ships today, so it stays — zeroing
- // it would restyle every CTA on the site, which is a different change from
- // keeping a long label inside its column.
+ // Restore only the label/icon gap. Primer .btn .octicon also has margin-right: 4px
+ // for leading icons, which lands outside these trailing CTA icons and gives 21px right
+ // inset against 17px left. Keep that asymmetry; zeroing it would restyle every CTA.
gap: 4px;
- // The octicon is a flex item now, and flex items shrink before their container
- // overflows. Once the label wraps, the icon is the only thing left to give, so
- // the 16px glyph was rendering at 11px in a 240px callout column. It is a
- // fixed-size icon; the label is what should absorb a narrow column.
+ // The octicon is a flex item, and flex items shrink before their container overflows.
+ // Once the label wraps, the icon is the only thing left to shrink, so the 16px glyph
+ // rendered at 11px in a 240px callout column. Keep the icon fixed and let the label absorb width.
.octicon {
flex-shrink: 0;
}
diff --git a/src/content-render/stylesheets/octicon-table-optimization.scss b/src/content-render/stylesheets/octicon-table-optimization.scss
index 23d1f9af5728..777b9d30f538 100644
--- a/src/content-render/stylesheets/octicon-table-optimization.scss
+++ b/src/content-render/stylesheets/octicon-table-optimization.scss
@@ -1,5 +1,5 @@
-// Octicon table optimization for pages with hundreds of repeated icons
-// Uses CSS background images instead of inline SVGs to dramatically reduce HTML size
+// Pages with hundreds of repeated octicons use CSS background images instead of inline SVGs
+// to reduce HTML size.
$octicon-check-path: "M13.78 4.22a.75.75 0 0 1 0 1.06l-7.25 7.25a.75.75 0 0 1-1.06 0L2.22 9.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018L6 10.94l6.72-6.72a.75.75 0 0 1 1.06 0Z";
$octicon-x-path: "M3.72 3.72a.75.75 0 0 1 1.06 0L8 6.94l3.22-3.22a.749.749 0 0 1 1.275.326.749.749 0 0 1-.215.734L9.06 8l3.22 3.22a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L8 9.06l-3.22 3.22a.751.751 0 0 1-1.042-.018.751.751 0 0 1-.018-1.042L6.94 8 3.72 4.78a.75.75 0 0 1 0-1.06Z";
diff --git a/src/content-render/stylesheets/syntax-highlighting.scss b/src/content-render/stylesheets/syntax-highlighting.scss
index 30b9b9efa5ae..e7b679732af0 100644
--- a/src/content-render/stylesheets/syntax-highlighting.scss
+++ b/src/content-render/stylesheets/syntax-highlighting.scss
@@ -8,10 +8,9 @@ from https://unpkg.com/highlight.js@9.15.8/styles/github.css
.hljs {
display: block;
padding: 0.5em;
- // The block's BASE text colour — the tokens below are prettylights, which has
- // no Brand equivalent and stays on Primer deliberately, but this one is just
- // "default text" and was painting Primer's #e6edf3 inside a Brand-framed code
- // block. The `background` is inert here (markdown-overrides paints the `pre`).
+ // Use Brand's default text color for the block itself. The syntax tokens below stay
+ // on Primer prettylights because Brand has no equivalent. Inside .markdown-body, Primer
+ // paints the pre and makes pre code transparent, so this background is inert there.
color: var(--brand-color-text-default);
background: var(--color-canvas-subtle);
}
diff --git a/src/data-directory/lib/data-directory.ts b/src/data-directory/lib/data-directory.ts
index 05e7049d93a6..56da0f47a565 100644
--- a/src/data-directory/lib/data-directory.ts
+++ b/src/data-directory/lib/data-directory.ts
@@ -17,6 +17,9 @@ interface DataDirectoryResult {
[key: string]: unknown
}
+// dataDirectory uses setWith because lodash set creates arrays for numeric release-note paths.
+// Example: release-notes.enterprise-server.2-20.0 must stay an object path.
+// See https://lodash.com/docs#set.
export default function dataDirectory(
dir: string,
opts: DataDirectoryOptions = {},
@@ -38,7 +41,6 @@ export default function dataDirectory(
const data: DataDirectoryResult = {}
- // find YAML and Markdown files in the given directory, recursively
const filenames = walk(dir, { includeBasePath: true }).filter((filename: string) => {
if (mergedOpts.ignorePatterns.some((pattern) => pattern.test(filename))) return false
@@ -51,7 +53,6 @@ export default function dataDirectory(
])
for (const [filename, fileContent] of files) {
- // derive `foo.bar.baz` object key from `foo/bar/baz.yml` filename
const key = filenameToKey(path.relative(dir, filename))
const extension = path.extname(filename).toLowerCase()
@@ -60,11 +61,6 @@ export default function dataDirectory(
processedContent = mergedOpts.preprocess(fileContent)
}
- // Add this file's data to the global data object.
- // Note we want to use `setWith` instead of `set` so we can customize the type during path creation.
- // If we just use `set`, then e.g. `release-notes.enterprise-server.2-20.0` will be an Array but
- // `release-notes.enterprise-server.3-0.0` will be an Object.
- // See https://lodash.com/docs#set for an explanation.
switch (extension) {
case '.json':
setWith(data, key, JSON.parse(processedContent), Object)
@@ -74,9 +70,7 @@ export default function dataDirectory(
break
case '.md':
case '.markdown':
- // Use `matter` to drop frontmatter, since localized reusable Markdown files
- // can potentially have frontmatter, but we want to prevent the frontmatter
- // from being rendered.
+ // Localized reusable Markdown can have frontmatter; strip it so content rendering hides it.
setWith(data, key, matter(processedContent).content, Object)
break
}
diff --git a/src/data-directory/lib/data-schemas/ctas.ts b/src/data-directory/lib/data-schemas/ctas.ts
index 2f97602bed03..31c2c0238c80 100644
--- a/src/data-directory/lib/data-schemas/ctas.ts
+++ b/src/data-directory/lib/data-schemas/ctas.ts
@@ -1,13 +1,9 @@
-// This schema enforces the structure for CTA (Call-to-Action) URL parameters
-// Used to validate CTA tracking parameters in documentation links
-
export default {
type: 'object',
additionalProperties: false,
required: ['ref_product', 'ref_type', 'ref_style'],
properties: {
- // GitHub Product: The GitHub product the CTA leads users to
- // Format: ref_product=copilot
+ // Example query parameter: ref_product=copilot.
ref_product: {
type: 'string',
name: 'Product',
@@ -26,8 +22,7 @@ export default {
],
},
- // Type of CTA: The type of action the CTA encourages users to take
- // Format: ref_type=trial
+ // Example query parameter: ref_type=trial.
ref_type: {
type: 'string',
name: 'Type',
@@ -35,8 +30,7 @@ export default {
enum: ['trial', 'purchase', 'engagement'],
},
- // CTA style: The way we are formatting the CTA in the docs
- // Format: ref_style=button
+ // Example query parameter: ref_style=button.
ref_style: {
type: 'string',
name: 'Style',
@@ -44,8 +38,7 @@ export default {
enum: ['button', 'text'],
},
- // Type of plan (Optional): For links to sign up for or trial a plan, the specific plan we link to
- // Format: ref_plan=business
+ // Example query parameter: ref_plan=business.
ref_plan: {
type: 'string',
name: 'Plan',
diff --git a/src/data-directory/lib/data-schemas/features.ts b/src/data-directory/lib/data-schemas/features.ts
index 1b9aa310350b..de81e35ff109 100644
--- a/src/data-directory/lib/data-schemas/features.ts
+++ b/src/data-directory/lib/data-schemas/features.ts
@@ -15,7 +15,6 @@ interface FeatureVersionsSchema {
additionalProperties: false
}
-// Copy the properties from the frontmatter schema.
const featureVersions: FeatureVersionsSchema = {
type: 'object',
properties: {
@@ -24,8 +23,7 @@ const featureVersions: FeatureVersionsSchema = {
additionalProperties: false,
}
-// Remove the feature versions properties.
-// We don't want to allow features within features! We just want pure versioning.
+// Each data/features file allows version gates but not nested feature gates.
delete (featureVersions.properties.versions.properties as Record | undefined)
?.feature
diff --git a/src/data-directory/lib/data-schemas/glossaries-candidates.ts b/src/data-directory/lib/data-schemas/glossaries-candidates.ts
index cfe6393c32a6..ae86460d98ac 100644
--- a/src/data-directory/lib/data-schemas/glossaries-candidates.ts
+++ b/src/data-directory/lib/data-schemas/glossaries-candidates.ts
@@ -7,7 +7,8 @@ export interface TermSchema {
export const term: TermSchema = {
type: 'string',
minLength: 1,
- pattern: '^((?!\\*).)*$', // no asterisks allowed
+ // Reject asterisks in glossary terms.
+ pattern: '^((?!\\*).)*$',
}
export interface GlossaryCandidateItem {
diff --git a/src/data-directory/lib/data-schemas/index.ts b/src/data-directory/lib/data-schemas/index.ts
index bd157c2afb63..9a082301823a 100644
--- a/src/data-directory/lib/data-schemas/index.ts
+++ b/src/data-directory/lib/data-schemas/index.ts
@@ -12,16 +12,14 @@ function resolveSchemaPath(filename: string): string {
const isTest = process.env.NODE_ENV === 'test'
if (isTest) {
- // Use relative paths that work for vitest and 4.x compatibility with
- // dynamic imports in particular
+ // Vitest dynamic imports need relative schema paths.
return `../lib/data-schemas/${filename}`
} else {
- // Use absolute paths that work for content linter and other contexts
+ // Content linter and other runtime contexts need absolute schema paths.
return `@/data-directory/lib/data-schemas/${filename}`
}
}
-// Auto-discover table schemas from data/tables/ directory
function loadTableSchemas(): DataSchemas {
const tablesDir = path.join(process.cwd(), 'data/tables')
const schemasDir = path.join(__dirname, 'tables')
@@ -43,7 +41,6 @@ function loadTableSchemas(): DataSchemas {
return tableSchemas
}
-// Manual schema registrations for non-table data
const manualSchemas: DataSchemas = {
'data/features': resolveSchemaPath('features.ts'),
'data/variables': resolveSchemaPath('variables.ts'),
@@ -51,9 +48,8 @@ const manualSchemas: DataSchemas = {
'data/code-languages.yml': resolveSchemaPath('code-languages.ts'),
'data/glossaries/candidates.yml': resolveSchemaPath('glossaries-candidates.ts'),
'data/glossaries/external.yml': resolveSchemaPath('glossaries-external.ts'),
- // Tables in subdirectories of data/tables are not picked up by loadTableSchemas(),
- // which only reads the top level, so the matrix is registered explicitly here.
- // The matrix/ entry is a directory schema: every per-IDE file is validated against it.
+ // Register the matrix directory schema because loadTableSchemas reads only top-level files.
+ // The directory schema validates every per-IDE file.
'data/tables/copilot/matrix': resolveSchemaPath('tables/copilot/matrix-ide.ts'),
'data/tables/copilot/matrix-meta.yml': resolveSchemaPath('tables/copilot/matrix-meta.ts'),
}
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/auto-model-selection.ts b/src/data-directory/lib/data-schemas/tables/copilot/auto-model-selection.ts
index 9b6ff927dd95..63b81d4f8cec 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/auto-model-selection.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/auto-model-selection.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in auto-model-selection.yml
-
const autoModelSelectionSchema = {
type: 'array',
items: {
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/matrix-ide.ts b/src/data-directory/lib/data-schemas/tables/copilot/matrix-ide.ts
index e91ddcc37c4c..e2b85f6cdc9b 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/matrix-ide.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/matrix-ide.ts
@@ -1,28 +1,15 @@
-// Schema for the per-IDE files in data/tables/copilot/matrix/
-//
-// Registered as a directory schema in src/data-directory/lib/data-schemas/index.ts,
-// so every file added to that directory is validated against this shape.
+// The directory schema registration validates every data/tables/copilot/matrix/.yml file.
-// Deliberately not an enum. The vocabulary is defined once, as data, in
-// matrix-meta.yml, and is enforced against every IDE file by the
-// 'every support level used is defined in matrix-meta' invariant in
-// src/data-directory/tests/copilot-matrix.ts. Repeating the values here would
-// be a fourth copy that can drift from the data — which is exactly what the
-// schema this file replaces did: it was missing 'closing-down'.
+// supportLevel stays open because matrix-meta.yml owns the vocabulary and tests enforce it.
+// Repeating values here would create a fourth copy that can drift from data.
const supportLevel = {
type: 'string',
}
-// Every version tracked here is 3-part, and that follows from what is tracked
-// rather than from convention: four of the six files track the Copilot
-// extension (marketplace versions are required to be x.y.z) and the two that
-// track the IDE itself, VS Code and Visual Studio, version that way natively.
-// Kept strict on purpose. It catches a dropped or added segment — the mistake
-// an updater reading release notes is most likely to make, and one the
-// cross-file invariants cannot see, since they only check that a version is
-// used consistently, not that it is real. If an IDE genuinely changes
-// versioning scheme, that is a deliberate decision: change this pattern and say
-// why in the PR.
+// All six matrix files use three-part versions: four track Copilot extension marketplace versions,
+// and VS Code and Visual Studio use three-part IDE versions natively.
+// Keep the pattern strict because cross-file tests catch consistency, not malformed versions.
+// Update this pattern if an IDE adopts a different version format.
const VERSION_PATTERN = '^\\d+\\.\\d+\\.\\d+$'
const copilotMatrixIdeSchema = {
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/matrix-meta.ts b/src/data-directory/lib/data-schemas/tables/copilot/matrix-meta.ts
index 8853dc696125..873642ba58e8 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/matrix-meta.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/matrix-meta.ts
@@ -1,7 +1,5 @@
-// Schema for data/tables/copilot/matrix-meta.yml
-//
-// Shared configuration for the Copilot IDE feature matrix. Per-IDE data lives in
-// data/tables/copilot/matrix/.yml and is validated by matrix-ide.ts.
+// matrix-meta.yml owns shared Copilot IDE matrix configuration.
+// Per-IDE data lives in data/tables/copilot/matrix/.yml and matrix-ide.ts validates it.
const copilotMatrixMetaSchema = {
type: 'object',
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/model-comparison.ts b/src/data-directory/lib/data-schemas/tables/copilot/model-comparison.ts
index 022eb8da25aa..6189c00e9ff6 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/model-comparison.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/model-comparison.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in model-comparison.yml
-
const modelComparisonSchema = {
type: 'object',
additionalProperties: false,
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/model-deprecation-history.ts b/src/data-directory/lib/data-schemas/tables/copilot/model-deprecation-history.ts
index ba31dc99efb6..84fc98abac18 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/model-deprecation-history.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/model-deprecation-history.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in model-deprecation-history.yml
-
const modelDeprecationHistorySchema = {
type: 'object',
additionalProperties: false,
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/model-release-status.ts b/src/data-directory/lib/data-schemas/tables/copilot/model-release-status.ts
index a00352c7735a..6918f92a8903 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/model-release-status.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/model-release-status.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in model-release-status.yml
-
const modelsReleaseStatusSchema = {
type: 'object',
additionalProperties: false,
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/model-supported-clients.ts b/src/data-directory/lib/data-schemas/tables/copilot/model-supported-clients.ts
index ffb28af36dc2..84475d8305aa 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/model-supported-clients.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/model-supported-clients.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in model-supported-clients.yml
-
const modelsSupportedClientsSchema = {
type: 'object',
additionalProperties: false,
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/model-supported-plans.ts b/src/data-directory/lib/data-schemas/tables/copilot/model-supported-plans.ts
index 401b46254091..1476e55a4774 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/model-supported-plans.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/model-supported-plans.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in model-supported-plans.yml
-
const modelSupportedPlansSchema = {
type: 'object',
additionalProperties: false,
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/models-and-pricing.ts b/src/data-directory/lib/data-schemas/tables/copilot/models-and-pricing.ts
index 96f8127cd22e..992153a91100 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/models-and-pricing.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/models-and-pricing.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in models-and-pricing.yml
-
const modelsAndPricingSchema = {
type: 'object',
additionalProperties: false,
diff --git a/src/data-directory/lib/data-schemas/tables/repository-roles.ts b/src/data-directory/lib/data-schemas/tables/repository-roles.ts
index 6774b9739d4b..ab0a2af84e5c 100644
--- a/src/data-directory/lib/data-schemas/tables/repository-roles.ts
+++ b/src/data-directory/lib/data-schemas/tables/repository-roles.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in data/tables/repository-roles.yml
-
const row = {
type: 'object',
additionalProperties: false,
@@ -9,13 +7,11 @@ const row = {
type: 'string',
lintable: true,
},
- // Liquid that renders non-empty when the row should be shown. When omitted,
- // the row is shown on every version.
+ // Non-empty Liquid output limits the row to matching versions; omitting it renders everywhere.
versions: {
type: 'string',
},
- // Comma separated list of the roles that can perform the action. Roles left
- // out render as no. May contain Liquid, so a single role can be conditional.
+ // Comma-separated roles can contain Liquid; omitted roles render as no.
roles: {
type: 'string',
},
diff --git a/src/data-directory/lib/data-schemas/tables/rest-api-versions.ts b/src/data-directory/lib/data-schemas/tables/rest-api-versions.ts
index 046c02afe403..b0e5aef2741d 100644
--- a/src/data-directory/lib/data-schemas/tables/rest-api-versions.ts
+++ b/src/data-directory/lib/data-schemas/tables/rest-api-versions.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in data/tables/rest-api-versions.yml
-
export default {
type: 'object',
additionalProperties: false,
diff --git a/src/data-directory/lib/data-schemas/tables/supported-code-languages.ts b/src/data-directory/lib/data-schemas/tables/supported-code-languages.ts
index a298f709ef15..a7836014e0d5 100644
--- a/src/data-directory/lib/data-schemas/tables/supported-code-languages.ts
+++ b/src/data-directory/lib/data-schemas/tables/supported-code-languages.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in data/tables/supported-code-languages.yml
-
export default {
type: 'object',
additionalProperties: false,
@@ -164,7 +162,7 @@ export default {
type: 'object',
additionalProperties: false,
patternProperties: {
- // Language names like C, C++, C#, Go, Java, JavaScript, etc.
+ // Matches language names like C, C++, C#, Go, Java, and JavaScript.
'^[a-zA-Z+#]+$': {
type: 'object',
additionalProperties: false,
@@ -188,15 +186,15 @@ export default {
},
codeScanning: {
type: 'string',
- // Allow "supported", "not-supported", or custom text like "third-party [^1]"
+ // Accepts supported, not-supported, or custom text such as "third-party [^1]".
},
depGraph: {
type: 'string',
- // Allow "supported", "not-supported", or specific package managers like "npm, Yarn"
+ // Accepts supported, not-supported, or package managers such as "npm, Yarn".
},
depUpdates: {
type: 'string',
- // Allow "supported", "not-supported", or specific package managers
+ // Accepts supported, not-supported, or package managers.
},
actions: {
type: 'string',
@@ -204,7 +202,7 @@ export default {
},
packages: {
type: 'string',
- // Allow "supported", "not-supported", or specific package managers
+ // Accepts supported, not-supported, or package managers.
},
},
},
diff --git a/src/data-directory/lib/filename-to-key.ts b/src/data-directory/lib/filename-to-key.ts
index e46c27903709..b9eaf51fbaf7 100644
--- a/src/data-directory/lib/filename-to-key.ts
+++ b/src/data-directory/lib/filename-to-key.ts
@@ -3,14 +3,12 @@ import path from 'path'
const leadingPathSeparator = new RegExp(`^${RegExp.escape(path.sep)}`)
const windowsLeadingPathSeparator = new RegExp('^/')
-// all slashes in the filename. path.sep is OS agnostic (windows, mac, etc)
+// path.sep handles the current OS; the slash and backslash regexes handle paths from other systems.
const pathSeparator = new RegExp(RegExp.escape(path.sep), 'g')
const windowsPathSeparator = new RegExp('/', 'g')
-// handle MS Windows style double-backslashed filenames
const windowsDoubleSlashSeparator = new RegExp('\\\\', 'g')
-// derive `foo.bar.baz` object key from `foo/bar/baz.yml` filename
export default function filenameToKey(filename: string): string {
const extension = new RegExp(`${RegExp.escape(path.extname(filename))}$`)
const key = filename
diff --git a/src/data-directory/lib/get-data.ts b/src/data-directory/lib/get-data.ts
index 65b3d8d8bc91..85f7acf1bd09 100644
--- a/src/data-directory/lib/get-data.ts
+++ b/src/data-directory/lib/get-data.ts
@@ -20,14 +20,10 @@ interface FileSystemError extends Error {
code?: string
}
-// If you run `export DEBUG_JIT_DATA_READS=true` in your terminal,
-// next time it will mention every file it reads from disk.
+// Set DEBUG_JIT_DATA_READS=true to log every data file read from disk.
const DEBUG_JIT_DATA_READS = Boolean(JSON.parse(process.env.DEBUG_JIT_DATA_READS || 'false'))
-// This is a list of files that we should always immediately fall back to
-// English for.
-// Having this is safer than trying to wrangle the translations to NOT
-// have them translated.
+// Product and Copilot paths belong in the English-only set; translations can change fixed names.
const ALWAYS_ENGLISH_YAML_FILES = new Set([
'data/variables/product.yml',
'data/variables/copilot.yml',
@@ -37,17 +33,13 @@ const ALWAYS_ENGLISH_MD_FILES = new Set([
'data/reusables/ssh/known_hosts.md',
])
-// Returns all the things inside a directory
export const getDeepDataByLanguage = memoize(
(dottedPath: string, langCode: string, dir: string | null = null): Record => {
if (!(langCode in languages)) {
throw new Error(`langCode '${langCode}' not a recognized language code`)
}
- // The `dir` argument is only used for testing purposes.
- // For example, our unit tests that depend on using a fixtures root.
- // If we don't allow those tests to override the `dir` argument,
- // it'll be stuck from the first time `languages.ts` was imported.
+ // Tests pass a fixture root because languages-server.ts captures directories when it loads.
if (dir === null) {
dir = languages[langCode].dir
}
@@ -55,8 +47,7 @@ export const getDeepDataByLanguage = memoize(
},
)
-// Doesn't need to be memoized because it's used by getDataKeysByLanguage
-// which is already memoized.
+// getDeepDataByLanguage caches each top-level path, so recursive reads need no extra cache.
function getDeepDataByDir(dottedPath: string, dir: string): Record {
const fullPath = ['data']
const split = dottedPath.split(/\./g)
@@ -66,7 +57,8 @@ function getDeepDataByDir(dottedPath: string, dir: string): Record {
const uiEnglish = getUIData('en')
if (langCode === 'en') return uiEnglish as UIStrings
- // Got to combine. Start with the English and put the translation on top.
- // E.g.
- // english = {food: "Food", drink: "Drink"}
- // swedish = {food: "Mat"}
- // =>
- // combind = {food: "Mat", drink: "Drink"}
+ // Merge translations over English so missing localized UI keys fall back to English.
const combined: Record = {}
merge(combined, uiEnglish)
merge(combined, getUIData(langCode))
return combined as UIStrings
})
-// Doesn't need to be memoized because it's used by another function
-// that is memoized.
+// getUIDataMerged memoizes results, so this reader needs no separate cache.
const getUIData = (langCode: string): Record => {
const fullPath = ['data', 'ui.yml']
const { dir } = languages[langCode]
return getYamlContent(dir, fullPath.join(path.sep)) as Record
}
+// When translated data misses a dotted path, retry English.
+// lodash get returns undefined for the missing dotted path instead of ENOENT.
export const getDataByLanguage = memoize((dottedPath: string, langCode: string): unknown => {
if (!(langCode in languages))
throw new Error(`langCode '${langCode}' not a recognized language code`)
@@ -116,32 +104,20 @@ export const getDataByLanguage = memoize((dottedPath: string, langCode: string):
try {
const value = getDataByDir(dottedPath, dir, languages.en.dir, langCode)
- // What could happens is that a new key has only been added to
- // the English data/ui.yml but hasn't been added to Japanese, but
- // there nevertheless exists a Japanese `data/ui.yml`.
- // Since getDataByDir() uses `get(dataObject, 'dott.ed.path')` it
- // will return `undefined` if it's not present.
- // If this happens, we can't rely on `err.code === 'ENOENT'` to
- // fall back the English one. So we just start over using the English data.
if (value === undefined && langCode !== 'en') {
return getDataByDir(dottedPath, languages.en.dir)
}
return value
} catch (error) {
if (error instanceof Error && (error as YAMLException).mark && error.message) {
- // It's a load() generated error!
- // Remember, the file that we read might have been a .yml or a .md
- // file. If it was a .md file, with corrupt front-matter that too
- // would have caused a YAMLException
+ // Corrupt YAML files and Markdown frontmatter raise YAMLException, so translations fall back.
if (langCode !== 'en') {
if (DEBUG_JIT_DATA_READS) {
logger.warn('Unable to parse Yaml in translation', { langCode, dottedPath, error })
}
- // Give it one more chance, but use English this time
return getDataByDir(dottedPath, languages.en.dir)
}
- // Always throw English Yaml reading errors. Staff writers
- // need to know early and explicitly that they are corrupt.
+ // Throw English YAML errors so staff writers see corrupt source data early.
throw error
}
@@ -150,6 +126,10 @@ export const getDataByLanguage = memoize((dottedPath: string, langCode: string):
}
})
+// getSmartSplit preserves dotted path segments such as version-3.4.
+// Release notes split normally because numeric paths such as 3-7/0.yml would combine incorrectly.
+// getDataByDir keeps {% data early-access.reusables.foo.bar %} under data/early-access.
+// That data lives at data/early-access/reusables/foo/bar.md.
function getDataByDir(
dottedPath: string,
dir: string,
@@ -158,28 +138,10 @@ function getDataByDir(
): unknown {
const fullPath = ['data']
- // Using English here because it doesn't matter. We just want to
- // figure out how to turn `foo.version-3.4.deeper.key' into
- // `['foo', 'version-3.4', 'deeper', 'key']` here and we'll need
- // any directory to do that and English is always the most up-to-date.
- // We need the getSmartSplit() as long as there's a chance that a
- // directory or file inside data/ might contain a dot in the name,
- // however the exception is the file names in data/release-notes/**/*.yml
- // because it contains files that are just numbers like 3-7/0.yml and
- // that can cause problems inside getSmartSplit().
const split = dottedPath.startsWith('release-notes')
? dottedPath.split('.')
: getSmartSplit(dottedPath)
- // For early-access data stuff, they're referred to as...
- //
- // {% data early-access.reusables.foo.bar %}
- //
- // When we "merge" in the early-access data, we put the whole directory
- // within the root `data/` so it exists, on disk, as
- //
- // data/early-access/reusables/foo/bar.md
- //
if (split[0] === 'early-access') {
fullPath.push(split.shift()!)
}
@@ -233,24 +195,12 @@ function getDataByDir(
const markdown = getMarkdownContent(dir, fullPath.join(path.sep), englishRoot)
let { content } = matter(markdown)
if (dir !== englishRoot) {
- // If we're reading a translation, we need to replace the possible
- // corruptions. For example `[AUTOTITLE"을](/foo/bar)`.
- // To do this we'll need the English equivalent
+ // Translated reusables need English content to fix corruptions like [AUTOTITLE"을](/foo/bar).
let englishContent = content
try {
englishContent = getMarkdownContent(englishRoot, fullPath.join(path.sep), englishRoot)
} catch (error) {
- // In some real but rare cases a reusable doesn't exist in English.
- // At all.
- // This can happen when the translation is really out of date.
- // You might have an old `docs-internal.locale/content/**/*.md`
- // file that mentions `{% data reusables.foo.bar %}`. And it's
- // working fine, except none of that exists in English.
- // If this is the case, we still want to executed the
- // correctTranslatedContentStrings() function, but we can't
- // genuinely give it the English equivalent content, which it
- // sometimes uses to correct some Liquid tags. At least other
- // good corrections might happen.
+ // Translated pages can reference reusables missing in English; other corrections still run.
if ((error as FileSystemError).code !== 'ENOENT') {
throw error
}
@@ -263,9 +213,9 @@ function getDataByDir(
return content
}
- // E.g. {% data ui.pages.foo.bar %}
+ // UI data references such as {% data ui.pages.foo.bar %} read from data/ui.yml.
if (first === 'ui') {
- const basename = split.shift() // i.e. 'ui'
+ const basename = split.shift()
fullPath.push(`${basename}.yml`)
const allData = getYamlContent(dir, fullPath.join(path.sep), englishRoot)
return get(allData, split.join('.'))
@@ -292,7 +242,7 @@ function getSmartSplit(dottedPath: string): string[] {
const next = split[i + 1]
if (/\d$/.test(bit) && /^\d/.test(next)) {
bits.push([bit, next].join('.'))
- i++ // jump ahead one position in the loop
+ i++
} else {
bits.push(bit)
}
@@ -301,36 +251,12 @@ function getSmartSplit(dottedPath: string): string[] {
return bits
}
-// The reason this is memoized, even though the parent caller function
-// (`getDataByLanguage`) is also memoized is because we might read
-// the same file for two different keys. E.g.
-//
-// getDataByLanguage('variables.product.prodname_ghe_server', 'en')
-// getDataByLanguage('variables.product.company_short', 'en')
-//
-// ...will actually depend on reading `data/variables/product.yml`. Twice.
-// Well, actually not twice because we cache the disk reading. So the outcome
-// becomes this:
-//
-// 1. getDataByLanguage('variables.product.prodname_ghe_server', 'en')
-// -> cache MISS
-// 1.1. read and parse data/variables/product.yml
-// -> cache MISS
-// 2. getDataByLanguage('variables.product.company_short', 'en')
-// -> cache MISS
-// 2.1. read and parse data/variables/product.yml
-// -> cache HIT (Yay!)
-//
+// getDataByLanguage caches each dotted key, but different keys can read the same YAML file.
+// Cache YAML reads too, so product name variables share data/variables/product.yml.
const getYamlContent = memoize(
(root: string | undefined, relPath: string, englishRoot?: string): unknown => {
- // Certain Yaml files we know we always want the English one
- // no matter what the specified language is.
- // For example, we never want `data/variables/product.yml` translated
- // so we know to immediately fall back to the English one.
if (ALWAYS_ENGLISH_YAML_FILES.has(relPath)) {
- // This forces it to read from English. Later, when it goes
- // into `getFileContent(...)` it will note that `root !== englishRoot`
- // so it won't try to fall back.
+ // Passing englishRoot prevents getFileContent from treating this as a translation fallback.
root = englishRoot
}
const fileContent = getFileContent(root, relPath, englishRoot)
@@ -338,13 +264,10 @@ const getYamlContent = memoize(
},
)
-// The reason why this is memoized, is the same as for getYamlContent() above.
+// Cache Markdown reads too because different dotted keys can hit the same file.
const getMarkdownContent = memoize(
(root: string | undefined, relPath: string, englishRoot?: string): string => {
- // Certain reusables we never want to be pulled from the translations.
- // For example, certain reusables don't contain any English prose. Just
- // facts like numbers or hardcoded key words.
- // If this is the case, forcibly always draw from the English files.
+ // SSH fingerprints and known_hosts contain facts, not prose, so they are meant to use English.
if (ALWAYS_ENGLISH_MD_FILES.has(relPath)) {
root = englishRoot
}
@@ -364,13 +287,9 @@ const getFileContent = (
try {
return fs.readFileSync(filePath, 'utf-8')
} catch (err) {
- // It might fail because that particular data entry doesn't yet
- // exist in a translation
if ((err as FileSystemError).code === 'ENOENT') {
- // If looking it up as a file fails, give it one more chance if the
- // read was for a translation.
if (englishRoot && root !== englishRoot) {
- // We can try again but this time using the English files
+ // Missing translated data falls back to English when an English root is available.
return getFileContent(englishRoot, relPath, englishRoot)
}
}
@@ -378,24 +297,15 @@ const getFileContent = (
}
}
+// Development bypasses caching because repeated sync reads stay cheap enough for debugging.
+// A benchmark sampled 10 common data files across 100 runs, with about 80% YAML files.
+// Median sync reads took 0.5 ms per 10 files, or 2.1 ms per 10 files with YAML parsing.
function memoize(
func: (...args: Args) => Return,
): (...args: Args) => Return {
const cache = new Map()
return (...args: Args) => {
if (process.env.NODE_ENV === 'development') {
- // It is very possible that certain files, when caching is disabled,
- // are read multiple times in short succession. E.g. `product.yml`.
- // So how expensive is it to read these files excessively?
- // To answer that, we benchmarked it by sampling 10 files from the
- // most common files that are used from `data/`. In fact, we ran 100
- // runs of 10 *different* files. About 80% of them were `.yml` files.
- // As a median, it takes **0.5ms to read 10 files from disk**
- // all in a sync manner.
- // Since most files coming through here is `.yml` files (e.g.
- // product.yml and ui.yml) if you also do the `load()` of the
- // read content, that number becomes **2.1ms to read and parse 10 files**.
- // So in conclusion, not a lot of time.
return func(...args)
}
diff --git a/src/data-directory/middleware/data-tables.ts b/src/data-directory/middleware/data-tables.ts
index 8edf5262f938..bb3ed7c20a32 100644
--- a/src/data-directory/middleware/data-tables.ts
+++ b/src/data-directory/middleware/data-tables.ts
@@ -6,13 +6,12 @@ let tablesCache: Record | null = null
const getTables = () => {
if (!tablesCache) {
- // Keep product-name-heavy reference tables in English only for now
+ // Product-name-heavy reference tables stay in English to avoid localized product names.
tablesCache = getDeepDataByLanguage('tables', 'en')
}
return tablesCache
}
-// Loads the YAML files under data/tables/ into req.context.
export default async function dataTables(req: ExtendedRequest, res: Response, next: NextFunction) {
if (!req.context) throw new Error('request not contextualized')
diff --git a/src/data-directory/scripts/deleted-features-pr-comment.ts b/src/data-directory/scripts/deleted-features-pr-comment.ts
index a601190d9c16..a88cc4565b36 100644
--- a/src/data-directory/scripts/deleted-features-pr-comment.ts
+++ b/src/data-directory/scripts/deleted-features-pr-comment.ts
@@ -1,12 +1,6 @@
-/**
- * This script is supposed to be used in Actions. When it's run in Actions
- * there will be an env var called GITHUB_REPOSITORY. If it's not there,
- * you can use this script as a CLI tool. For example:
- *
- * export GITHUB_TOKEN=github_pat_blablabla
- * npm run deleted-features-pr-comment -- github docs-internal main 2ba53b6a
- *
- */
+// Produces deleted-feature Markdown as an Actions output; without GITHUB_REPOSITORY, prints it.
+// Required: GITHUB_TOKEN.
+// CLI: npm run deleted-features-pr-comment -- github docs-internal main 2ba53b6a
import { context as github_context, getOctokit } from '@actions/github'
import { setOutput } from '@actions/core'
@@ -44,7 +38,6 @@ async function main(owner: string, repo: string, baseSHA: string, headSHA: strin
throw new Error(`GITHUB_TOKEN environment variable not set`)
}
const octokit = getOctokit(GITHUB_TOKEN)
- // get the list of file changes from the PR
const response = await octokit.rest.repos.compareCommitsWithBasehead({
owner,
repo,
@@ -62,10 +55,10 @@ async function main(owner: string, repo: string, baseSHA: string, headSHA: strin
console.warn(`Feature involved in this PR: ${filename}; Status: ${status}`)
if (status === 'removed') {
- // Bad
+ // Deleted feature files can stay referenced in translated content.
oldFilenames.push(filename)
} else if (status === 'renamed') {
- // Also bad
+ // Renamed feature files can stay referenced by the old name in translated content.
const previousFilename = file.previous_filename
oldFilenames.push(previousFilename)
} else {
diff --git a/src/data-directory/scripts/find-orphaned-features/find.ts b/src/data-directory/scripts/find-orphaned-features/find.ts
index 2398738b896c..43f7b73afde0 100644
--- a/src/data-directory/scripts/find-orphaned-features/find.ts
+++ b/src/data-directory/scripts/find-orphaned-features/find.ts
@@ -1,31 +1,8 @@
-/**
- * This script will loop over all pages, in all languages, and look at
- * the following:
- *
- * 1. `title` in frontmatter
- * 2. `intro` in frontmatter
- * 3. `shortTitle` in frontmatter (if present)
- * 4. the markdown body itself
- * 5. The `versions:` frontmatter key (if the page is in English)
- *
- * Then it will search out the features mentioned based on `data/features/*.yml`
- * It will make a Set of these (e.g. `dependabot-grouped-dependencies` and
- * `ghas-enablement-webhook`) and one by one pluck them away.
- *
- * After the pages, it will loop over the reusables in English, and do the
- * same search there. Once it's done the English, it loops over the
- * reusables in the translations (if they exist) and does the same search.
- *
- * Lastly, it will output the remaining features, as relative file paths.
- * For example, `data/features/havent-been-used-in-years.yml` so now you
- * know that file can be deleted.
- *
- * NOTE: A lot of translations have corrupted Liquid. So if we can't parse
- * the Liquid we fall back to string search. A regex will try to find
- * all `{% ifversion ... %}` (and `elsif`) and search for any features
- * mentioned inside that as a string.
- *
- */
+// Finds data/features/*.yml entries that no page, reusable, or variable references.
+// It scans title, intro, shortTitle, body, and English versions frontmatter across all pages.
+// It also scans English reusables and variables, then matching translated reusables.
+// Outputs remaining features as paths such as data/features/havent-been-used-in-years.yml.
+// If translated Liquid cannot parse, regex searches feature names in ifversion and elsif tags.
import { strictEqual } from 'node:assert'
import fs from 'fs'
@@ -118,12 +95,12 @@ function formatDelta(t0: Date, t1: Date) {
return `${(ms / 1000).toFixed(1)} seconds`
}
+// searchAndRemove scans translated reusables only when English has the same relative path.
+// English content lets correctTranslatedContentStrings repair Liquid before feature matching.
function searchAndRemove(features: Set, pages: Page[], verbose = false) {
for (const page of pages) {
const content = page.markdown
- // We actually never bother looking at the `versions:` frontmatter
- // key in translations, so it doesn't matter if the translated
- // frontmatter might have `versions: some-old-feature`.
+ // Only English versions frontmatter can mark a feature used.
if (page.languageCode === 'en') {
for (const [key, value] of Object.entries(page.versions)) {
if (key === 'feature') {
@@ -144,19 +121,6 @@ function searchAndRemove(features: Set, pages: Page[], verbose = false)
checkString(combined, features, { page, verbose, languageCode: page.languageCode })
}
- // Reusables are a bit special, as they are shared between languages.
- // There'll always be a slight mismatch between files present on disk
- // in English vs. translations.
- // The translations never delete files, so there's often excess reusables
- // on disk in translations. And the English might be ahead, meaning a file
- // has been introduced in English but not yet translated.
- // The code below loops over the English reusables, and takes note of the
- // their relative paths and content. Then, we re-use the keys of that map
- // to know which files, in the translations, to check. And when we read
- // them in, we'll need the English equivalent content to be able to
- // use the correctTranslatedContentStrings function.
-
- // Check the English variable files.
for (const filePath of getVariableFiles(path.join(languages.en.dir, 'data', 'variables'))) {
const fileContent = fs.readFileSync(filePath, 'utf-8')
checkString(fileContent, features, { filePath, verbose, languageCode: 'en' })
@@ -170,7 +134,7 @@ function searchAndRemove(features: Set, pages: Page[], verbose = false)
englishReusables.set(relativePath, fileContent)
}
for (const language of Object.values(languages)) {
- if (language.code === 'en') continue // Already did that in the loop above
+ if (language.code === 'en') continue
for (const [relativePath, englishFileContent] of Array.from(englishReusables.entries())) {
const filePath = path.join(language.dir, relativePath)
@@ -192,10 +156,7 @@ function searchAndRemove(features: Set, pages: Page[], verbose = false)
})
} catch (error) {
if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
- // That a reusable does *not* exist in a translation is
- // perfectly expected. It means that English reusable was
- // most likely added recently and the translation hasn't been
- // translated yet.
+ // Missing translated reusables are expected when English has newer files.
continue
}
throw error
@@ -243,10 +204,7 @@ function checkString(
}: { page?: Page; filePath?: string; languageCode?: string; verbose?: boolean } = {},
) {
try {
- // The reason for the `noCache: true` is that we're going to be sending
- // a LOT of different strings in and the cache will fill up rapidly
- // when testing every possible string in every possible language for
- // every page.
+ // Disable the Liquid token cache because scanning many different strings would fill it quickly.
const tokens = getLiquidTokens(string, { noCache: true }).filter(
(token): token is TagToken => token.kind === TokenKind.Tag,
)
@@ -264,11 +222,10 @@ function checkString(
}
} catch (error) {
if (error instanceof TokenizationError) {
- // If it happens in English, it's a serious error
+ // English Liquid parse failures are source errors.
if (languageCode === 'en') throw error
- // The translation might, currently, have corrupted liquid
- // So treat it as a string
+ // Translated Liquid can be corrupt, so regex search still catches feature references.
if (verbose)
console.log(
`TokenizationError in ${page ? page.fullPath : filePath}. Treating ${page ? page.fullPath : filePath} as a string and using regex`,
diff --git a/src/data-directory/scripts/find-orphaned-tables.ts b/src/data-directory/scripts/find-orphaned-tables.ts
index a254863b9b6a..9ce6e3e74898 100644
--- a/src/data-directory/scripts/find-orphaned-tables.ts
+++ b/src/data-directory/scripts/find-orphaned-tables.ts
@@ -1,20 +1,6 @@
-// [start-readme]
-//
-// Print a list of all the YAML-powered table files in ./data/tables/ that
-// can't be found mentioned in any source file (content, data & code), along
-// with their paired schema files. Mirrors find-orphaned-assets.ts.
-//
-// Tables are referenced from Liquid like:
-//
-// {% data tables.. %}
-// {% for entry in tables.. %}
-//
-// so a table file `data/tables//.yml` is "used" if the string
-// `tables..` appears anywhere. A deeper reference such as
-// `tables...` also counts, because the file key is a
-// prefix of it.
-//
-// [end-readme]
+// Prints unreferenced YAML-powered table files under ./data/tables/ and paired schema files.
+// Both {% data tables.copilot.matrix-meta %} and
+// {% for level in tables.copilot.matrix-meta.supportLevels %} mark the table used.
import fs from 'fs'
import path from 'path'
@@ -28,17 +14,15 @@ import languages from '@/languages/lib/languages-server'
const TABLES_DIR = 'data/tables'
const SCHEMAS_DIR = 'src/data-directory/lib/data-schemas/tables'
-// Tables that are referenced dynamically (not via Liquid) and must never be
-// flagged as orphans. Add an entry here (the dotted key, e.g. `copilot.foo`)
-// if a table is loaded by code rather than mentioned in content.
+// EXCEPTIONS protects tables loaded dynamically by code rather than mentioned in content.
const EXCEPTIONS = new Set([])
export type TableFile = {
- // Repo-relative path to the YAML file, e.g. data/tables/copilot/model-multipliers.yml
+ // Repo-relative YAML path, such as data/tables/copilot/model-multipliers.yml.
yml: string
// Repo-relative path to the paired schema, if it exists on disk.
schema?: string
- // Dotted key used in Liquid, e.g. copilot.model-multipliers
+ // Dotted Liquid key, such as copilot.model-multipliers.
key: string
}
@@ -72,9 +56,7 @@ type MainOptions = {
excludeTranslations: boolean
}
-// Given the table files and the contents of every source file, return the
-// tables whose Liquid key is never mentioned. Pulled out of main() so it can
-// be unit tested without touching the filesystem.
+// Exported for tests so orphan detection can run without filesystem reads.
export function getOrphanedTables(
tables: TableFile[],
sourceContents: Iterable,
@@ -91,8 +73,7 @@ export function getOrphanedTables(
return [...orphans.values()].sort((a, b) => a.yml.localeCompare(b.yml))
}
-// Only parse argv and run when invoked directly (e.g. via `npm run
-// find-orphaned-tables`), not when imported by a test.
+// Guard main so tests can import getOrphanedTables; npm run find-orphaned-tables invokes it.
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
program.parse(process.argv)
main(program.opts())
@@ -108,10 +89,7 @@ async function main(opts: MainOptions) {
const sourceFiles: string[] = [...englishFiles]
if (!excludeTranslations) {
- // Translations are often behind English. A table can still be referenced
- // in a translation even when no English content references it, so we must
- // search translations too. We only look at files that also exist in
- // English, because translations rarely delete renamed/removed files.
+ // Search matching translations because translated content can still reference a table.
const englishRelativeFiles = new Set(
englishFiles.map((englishFile) => path.relative(languages.en.dir, englishFile)),
)
@@ -133,9 +111,7 @@ async function main(opts: MainOptions) {
}
}
- // Tables can also be referenced from code (e.g. table-rendering helpers), so
- // search src and contributing as well. Searching more files only ever marks
- // a table as used, never as an orphan, so it errs on the safe side.
+ // Search code because table-rendering helpers can reference tables without Liquid.
for (const root of ['contributing', 'src']) {
if (!fs.existsSync(root)) continue
sourceFiles.push(
@@ -165,9 +141,7 @@ async function main(opts: MainOptions) {
const orphanTables = getOrphanedTables(tables, readContents())
- // Safety net: if every table looks orphaned, the detection is almost
- // certainly broken (e.g. content wasn't checked out). Refuse to suggest
- // deleting everything.
+ // If every table looks orphaned, detection is probably broken; refuse to list deletions.
if (tables.length > 0 && orphanTables.length === tables.length) {
console.error(
'Every table was flagged as orphaned, which is almost certainly a bug. ' +
diff --git a/src/data-directory/tests/copilot-matrix.ts b/src/data-directory/tests/copilot-matrix.ts
index d12ec6ae8f8e..529344ab9c43 100644
--- a/src/data-directory/tests/copilot-matrix.ts
+++ b/src/data-directory/tests/copilot-matrix.ts
@@ -4,23 +4,14 @@ import { join } from 'path'
import { load } from 'js-yaml'
import { describe, expect, test } from 'vitest'
-// Cross-file invariants for the Copilot IDE feature matrix.
-//
-// The JSON schemas validate each file in isolation. These tests cover the
-// relationships *between* matrix-meta.yml and the per-IDE files, which is where
-// a hand edit — or, later, an automated changelog-driven update — is most
-// likely to introduce a silent error.
-//
-// "Silent" is the operative word: a missing or mistyped key does not raise an
-// error, it renders as ✗ (not supported) to customers.
+// JSON schemas validate each file in isolation. These tests cover cross-file matrix relationships.
+// Missing or mistyped keys silently render as ✗ (not supported) in customer-facing tables.
const MATRIX_DIR = join(process.cwd(), 'data/tables/copilot/matrix')
const META_PATH = join(process.cwd(), 'data/tables/copilot/matrix-meta.yml')
-// Stands for "supported since before we tracked versions". Some IDEs list it in
-// `versions` without putting it in a `versionGroup`, so it is the one version
-// allowed to have no detail table. Removing it is a customer-visible content
-// decision; until then it is excluded from the grouping invariant below.
+// Some IDEs use 0.0.0 for supported-before-tracking without a versionGroup.
+// Removing the sentinel is customer-visible, so the grouping invariant excludes it.
const SENTINEL_VERSION = '0.0.0'
type Ide = {
@@ -70,8 +61,7 @@ describe('copilot matrix meta', () => {
expect(new Set(meta.featureOrder).size).toBe(meta.featureOrder.length)
})
- // A stale featureOrder entry that no IDE uses renders as a row of ✗ across
- // every column of the summary table.
+ // A stale featureOrder entry renders as a row of ✗ across every summary-table column.
test('every featureOrder entry is used by at least one IDE', () => {
const used = new Set()
for (const ide of Object.values(ides)) {
@@ -114,13 +104,9 @@ describe.each(ideFilenames)('copilot matrix: %s', (slug) => {
).toEqual([])
})
- // Only versions listed in a versionGroup are rendered as a detail table. A
- // version in `versions` that is in no group is data customers cannot see —
- // and the summary table reads `versions | first`, so if it is the newest one
- // the page shows support data for a version with no detail table at all.
- // This is the most likely mistake for an automated updater that appends to
- // `versions` and forgets `versionGroups`, and checking only the newest
- // version would miss a backfilled older one.
+ // Only versions listed in versionGroups render detail tables. The test skips the 0.0.0 sentinel.
+ // The summary table reads versions | first, so an ungrouped newest version has no detail table.
+ // Checking every version also catches backfilled older versions that automated updates miss.
test('every version appears in at least one versionGroup', () => {
const grouped = new Set(Object.values(ide.versionGroups).flat())
const ungrouped = ide.versions.filter(
diff --git a/src/data-directory/tests/data-schemas.ts b/src/data-directory/tests/data-schemas.ts
index 7dd168ade55b..bc2b83a61f37 100644
--- a/src/data-directory/tests/data-schemas.ts
+++ b/src/data-directory/tests/data-schemas.ts
@@ -64,7 +64,6 @@ describe('YAML-powered tables', () => {
const schemaPath = join(schemasDir, `${name}.ts`)
expect(existsSync(schemaPath)).toBe(true)
- // Also verify it's registered in the dataSchemas
const dataKey = `data/tables/${yamlFile}`
expect(dataSchemas[dataKey]).toBeDefined()
}
diff --git a/src/data-directory/tests/find-orphaned-tables.ts b/src/data-directory/tests/find-orphaned-tables.ts
index b3ac92a04978..1dfc47015020 100644
--- a/src/data-directory/tests/find-orphaned-tables.ts
+++ b/src/data-directory/tests/find-orphaned-tables.ts
@@ -41,8 +41,6 @@ describe('getOrphanedTables', () => {
})
test('counts a deeper sub-key reference as using the table file', () => {
- // A reference to `tables.copilot.copilot-matrix.ides` should mark the
- // `copilot.copilot-matrix` file as used.
const orphans = getOrphanedTables(
[table('copilot.copilot-matrix')],
['{% for row in tables.copilot.copilot-matrix.ides %}'],
@@ -51,8 +49,6 @@ describe('getOrphanedTables', () => {
})
test('does not let a longer key falsely mark a shorter, unrelated table', () => {
- // `tables.copilot.annual-subscriber-model-multipliers` must NOT mark
- // `copilot.model-multipliers` as used.
const orphans = getOrphanedTables(
[table('copilot.model-multipliers')],
['{% data tables.copilot.annual-subscriber-model-multipliers %}'],
diff --git a/src/data-directory/tests/get-data.ts b/src/data-directory/tests/get-data.ts
index 7b3a0414f929..68e834bce35e 100644
--- a/src/data-directory/tests/get-data.ts
+++ b/src/data-directory/tests/get-data.ts
@@ -14,7 +14,7 @@ import { DataDirectory } from '@/tests/helpers/data-directory'
describe('get-data', () => {
let dd: DataDirectory
const enDirBefore = languages.en.dir
- // Only `en` is available in tests, so pretend we also have Japanese
+ // Only en is available in tests, so copy English metadata for Japanese fixtures.
languages.ja = Object.assign({}, languages.en, {})
beforeAll(() => {
@@ -77,12 +77,10 @@ describe('get-data', () => {
const result = getDataByLanguage('variables.stuff.foo', 'en')
expect(result).toBe('Foo')
}
- // Test that memoization doesn't go wrong
{
const result = getDataByLanguage('variables.stuff.bar', 'en')
expect(result).toBe('Bar')
}
- // Test that unrecognized keys just return `undefined`
{
const result = getDataByLanguage('variables.stuff.neverheardof', 'en')
expect(result).toBeUndefined()
@@ -94,12 +92,10 @@ describe('get-data', () => {
const result = getDataByLanguage('variables.stuff.foo', 'ja')
expect(result).toBe('フー')
}
- // Test fallback to English if not present in translation
{
const result = getDataByLanguage('variables.stuff.bar', 'ja')
expect(result).toBe('Bar')
}
- // Test that unrecognized keys just return `undefined`
{
const result = getDataByLanguage('variables.stuff.neverheardof', 'ja')
expect(result).toBeUndefined()
@@ -111,12 +107,10 @@ describe('get-data', () => {
const result = getDataByLanguage('variables.stuff.key_non_existent', 'en')
expect(result).toBeUndefined()
}
- // Test fallback to English if not present in translation
{
const result = getDataByLanguage('variables.stuff.key_non_existent', 'ja')
expect(result).toBeUndefined()
}
- // Returns undefined if not only the key is missing but the whole file too
{
const result = getDataByLanguage('variables.notpresent.whatever', 'en')
expect(result).toBeUndefined()
@@ -128,7 +122,6 @@ describe('get-data', () => {
const result = getDataByLanguage('reusables.coolness', 'en')
expect(result).toBe('This is *Markdown*')
}
- // Test that memoization doesn't go wrong
{
const result = getDataByLanguage('reusables.otherness', 'en')
expect(result).toBe('**Also** Markdown')
@@ -140,7 +133,6 @@ describe('get-data', () => {
const result = getDataByLanguage('reusables.coolness', 'ja')
expect(result).toBe('これがマークダウンです')
}
- // Test translations fall back to English if file doesn't exist
{
const result = getDataByLanguage('reusables.otherness', 'ja')
expect(result).toBe('**Also** Markdown')
@@ -152,7 +144,6 @@ describe('get-data', () => {
const result = getDataByLanguage('reusables.neverheardof', 'en')
expect(result).toBeUndefined()
}
- // Test translations will try English but fail if the fallback fails too
{
const result = getDataByLanguage('reusables.neverheardof', 'ja')
expect(result).toBeUndefined()
@@ -165,12 +156,10 @@ describe('get-data', () => {
expect(result.key).toBe('Value')
expect((result.deep as Record).er).toBe('Depth')
}
- // In a specific language
{
const result = getUIDataMerged('ja')
expect(result.key).toBe('価値')
expect((result.deep as Record).er).toBe('深さ')
- // Note how it falls back to English on that key
expect((result.deep as Record).est).toBe('Deepest')
}
})
@@ -181,7 +170,6 @@ describe('get-data', () => {
expect((result.stuff as Record).foo).toBe('Foo')
expect((result.stuff as Record).bar).toBe('Bar')
}
- // All reusables
{
const result = getDeepDataByLanguage('reusables', 'en')
expect(result['coolness.md']).toBe('This is *Markdown*')
@@ -213,7 +201,7 @@ front: >'matter
describe('get-data on corrupt translations', () => {
let dd: DataDirectory
const enDirBefore = languages.en.dir
- // Only `en` is available in vitest tests, so pretend we also have Japanese
+ // Only en is available in tests, so copy English metadata for Japanese fixtures.
languages.ja = Object.assign({}, languages.en, {})
beforeAll(() => {
@@ -263,12 +251,10 @@ describe('get-data on corrupt translations', () => {
})
test('getDataByLanguage on a corrupt .yml file', () => {
- // First make sure it works in English
{
const result = getDataByLanguage('variables.everything.is', 'en')
expect(result).toBe('Awesome')
}
- // Japanese translations would fall back due to a corrupt Yaml file
{
const result = getDataByLanguage('variables.everything.is', 'ja')
expect(result).toBe('Awesome')
@@ -276,12 +262,10 @@ describe('get-data on corrupt translations', () => {
})
test('getDataByLanguage on a corrupt .md file', () => {
- // First make sure it works in English
{
const result = getDataByLanguage('reusables.cool', 'en')
expect(result).toBe('*English* /Markdown/')
}
- // Japanese translations would fall back due to a corrupt Yaml file
{
const result = getDataByLanguage('reusables.cool', 'ja')
expect(result).toBe('*English* /Markdown/')
@@ -317,11 +301,11 @@ describe('get-data applies corrections to translated variables', () => {
data: {
variables: {
myproduct: {
- // Corrupted: `data` translated to Japanese `データ`
+ // Translation corrupts the data keyword to データ.
name: '{% データ variables.myproduct.name %}',
},
phases: {
- // Not corrupted, so it should pass through unchanged
+ // Valid ifversion stays unchanged.
preview: '{% ifversion ghes < 3.16 %}ベータ{% else %}パブリックプレビュー{% endif %}',
},
},
@@ -337,12 +321,10 @@ describe('get-data applies corrections to translated variables', () => {
})
test('corrects corrupted Liquid keywords in translated variables', () => {
- // English variable is returned as-is
{
const result = getDataByLanguage('variables.myproduct.name', 'en')
expect(result).toBe('GitHub')
}
- // Japanese translation with corrupted `データ` → `data` gets corrected
{
const result = getDataByLanguage('variables.myproduct.name', 'ja')
expect(result).toBe('{% data variables.myproduct.name %}')
@@ -350,7 +332,6 @@ describe('get-data applies corrections to translated variables', () => {
})
test('leaves valid translated variables unchanged', () => {
- // Valid ifversion in translated variable should pass through
{
const result = getDataByLanguage('variables.phases.preview', 'ja')
expect(result).toBe(
diff --git a/src/data-directory/tests/index.ts b/src/data-directory/tests/index.ts
index cdef3164a438..03e0de1a292b 100644
--- a/src/data-directory/tests/index.ts
+++ b/src/data-directory/tests/index.ts
@@ -31,16 +31,14 @@ describe('data-directory', () => {
const extensions = ['.yml', 'markdown']
const data = dataDirectory(fixturesDir, { extensions })
expect('bar' in data).toBe(true)
- expect('foo' in data).toBe(false) // JSON file should be ignored
+ expect('foo' in data).toBe(false)
})
test('option: ignorePatterns', async () => {
const ignorePatterns: RegExp[] = []
- // README is ignored by default
expect('README' in dataDirectory(fixturesDir)).toBe(false)
- // README can be included by setting empty ignorePatterns array
expect('README' in dataDirectory(fixturesDir, { ignorePatterns })).toBe(true)
})
})
diff --git a/src/data-directory/tests/orphaned-features.ts b/src/data-directory/tests/orphaned-features.ts
index ea931b6b4f21..e63c7c1f8db7 100644
--- a/src/data-directory/tests/orphaned-features.ts
+++ b/src/data-directory/tests/orphaned-features.ts
@@ -49,7 +49,6 @@ describe('orphaned features detection', () => {
})
test('helper functions handle nested directories', () => {
- // Create a temporary nested structure to test
const tempDir = path.join(__dirname, 'temp-nested-test')
const nestedVariablesDir = path.join(tempDir, 'variables', 'nested')
const nestedReusablesDir = path.join(tempDir, 'reusables', 'nested')
@@ -78,7 +77,6 @@ describe('orphaned features detection', () => {
})
test('helper functions ignore non-target files', () => {
- // Create a temporary directory with mixed file types
const tempDir = path.join(__dirname, 'temp-mixed-files')
fs.mkdirSync(tempDir, { recursive: true })
@@ -90,12 +88,10 @@ describe('orphaned features detection', () => {
fs.writeFileSync(path.join(tempDir, 'README.md'), '# README')
try {
- // getVariableFiles should only find .yml files (excluding README.yml)
const variableFiles = getVariableFiles(tempDir)
expect(variableFiles).toHaveLength(1)
expect(variableFiles[0]).toMatch(/test\.yml$/)
- // getReusableFiles should only find .md files (excluding README.md)
const reusableFiles = getReusableFiles(tempDir)
expect(reusableFiles).toHaveLength(1)
expect(reusableFiles[0]).toMatch(/test\.md$/)
@@ -105,13 +101,9 @@ describe('orphaned features detection', () => {
})
test('verify fix addresses the original issue scenario', () => {
- // This test simulates the original issue where features were used only in variables
- // but not detected by the orphaned features script
-
const variablesDir = path.join(fixturesDir, 'data', 'variables')
const featuresDir = path.join(fixturesDir, 'data', 'features')
- // Verify our test setup has the scenario described in the issue
expect(fs.existsSync(path.join(featuresDir, 'used-in-variables.yml'))).toBe(true)
expect(fs.existsSync(path.join(featuresDir, 'truly-orphaned.yml'))).toBe(true)
@@ -121,8 +113,6 @@ describe('orphaned features detection', () => {
const variableFiles = getVariableFiles(variablesDir)
expect(variableFiles.length).toBeGreaterThan(0)
- // This proves that the fix would catch features used in variables files
- // because the orphaned features script now scans these files
const foundFeatureUsage = variableFiles.some((filePath) => {
const content = fs.readFileSync(filePath, 'utf-8')
return content.includes('used-in-variables')
@@ -132,8 +122,6 @@ describe('orphaned features detection', () => {
})
test('functions correctly identify different file types in same directory', () => {
- // Create a directory with both .yml and .md files to ensure each function
- // only picks up its target file types
const tempDir = path.join(__dirname, 'temp-mixed-target-files')
fs.mkdirSync(tempDir, { recursive: true })
@@ -148,7 +136,6 @@ describe('orphaned features detection', () => {
fs.writeFileSync(path.join(tempDir, 'other.txt'), 'other content')
try {
- // Each function should only find its target file type
const variableFiles = getVariableFiles(tempDir)
const reusableFiles = getReusableFiles(tempDir)
diff --git a/src/data-directory/tests/ui-yml-structure.ts b/src/data-directory/tests/ui-yml-structure.ts
index edc8cf7e789a..91803b1c281e 100644
--- a/src/data-directory/tests/ui-yml-structure.ts
+++ b/src/data-directory/tests/ui-yml-structure.ts
@@ -13,7 +13,7 @@ describe('data/ui.yml structure', () => {
const violations: string[] = []
for (let i = 0; i < lines.length; i++) {
- // A top-level key starts at column 0 with a word followed by ':'
+ // Top-level keys start at column 0 with a word followed by colon.
if (/^[a-z_]+:/.test(lines[i]) && i > 0) {
if (lines[i - 1].trim() !== '') {
violations.push(`Line ${i + 1}: "${lines[i]}" is not preceded by a blank line`)
diff --git a/src/deployments/production/build-scripts/clone-or-use-cached-repo.sh b/src/deployments/production/build-scripts/clone-or-use-cached-repo.sh
index a908885ab652..0dad817f3ff9 100644
--- a/src/deployments/production/build-scripts/clone-or-use-cached-repo.sh
+++ b/src/deployments/production/build-scripts/clone-or-use-cached-repo.sh
@@ -1,11 +1,7 @@
set -e
-# Reuses the repo cached by a previous Dockerfile build, or clones it fresh
-# and checks out the given branch/SHA.
-# Arguments:
-# $1 - Repository name (for directory naming)
-# $2 - Repository URL
-# $3 - Branch to clone
+# Reuses a cached repo or clones it, then checks out the requested branch.
+# Arguments: $1 cache directory, $2 GitHub repo name under github, $3 branch.
clone_or_use_cached_repo() {
repo_name="$1"
repo_url="$2"
diff --git a/src/deployments/production/build-scripts/fetch-repos.sh b/src/deployments/production/build-scripts/fetch-repos.sh
index 3f2239fc448e..9f24050f0013 100644
--- a/src/deployments/production/build-scripts/fetch-repos.sh
+++ b/src/deployments/production/build-scripts/fetch-repos.sh
@@ -1,7 +1,7 @@
#!/usr/bin/env sh
-# Called from the production Dockerfile. The Dockerfile only COPYs what it
-# needs, but these scripts still run as if from the docs-internal root.
+# The production Dockerfile copies only required files, but these scripts still run from the
+# docs-internal root.
echo "Fetching and resolving early-access, and translations repos"
@@ -9,7 +9,7 @@ set -e
. ./build-scripts/clone-or-use-cached-repo.sh
-# From the --secret mounted by the Docker build.
+# Docker build mounts DOCS_BOT_PAT_BASE at /run/secrets/DOCS_BOT_PAT_BASE.
GITHUB_TOKEN=$(cat /run/secrets/DOCS_BOT_PAT_BASE)
echo "Fetching early access..."
@@ -17,11 +17,11 @@ clone_or_use_cached_repo "docs-early-access" "docs-early-access" "main"
echo "Merging early access..."
. ./build-scripts/merge-early-access.sh
-# Clone into `translations/` inside the Dockerfile's WORKDIR, the docs-internal root.
+# Clone translations under the Dockerfile WORKDIR, the docs-internal root.
mkdir -p translations
cd translations
-# Temporarily turn off exit-on-error so we can collect all PIDs
+# Disable exit-on-error so the script can collect every background clone failure.
set +e
pids=""
@@ -35,7 +35,6 @@ for pid in $pids; do
wait "$pid" || failures=$((failures+1))
done
-# Restore strict mode
set -e
if [ "$failures" -gt 0 ]; then
@@ -45,8 +44,8 @@ else
echo "✅ All translations fetched."
fi
-# Go back to the root of the docs-internal repo
+# Return to the docs-internal root after cloning translations.
cd ..
-# Don't leave the token in the environment.
+# Remove the token from the shell environment.
unset GITHUB_TOKEN
diff --git a/src/deployments/production/build-scripts/merge-early-access.sh b/src/deployments/production/build-scripts/merge-early-access.sh
index 317f81a9dc87..00a3c3bfef7a 100755
--- a/src/deployments/production/build-scripts/merge-early-access.sh
+++ b/src/deployments/production/build-scripts/merge-early-access.sh
@@ -1,7 +1,6 @@
#!/usr/bin/env sh
-# Merges docs-early-access files into docs-internal. Runs from the
-# docs-internal root.
+# Merges docs-early-access files into docs-internal from the docs-internal root.
mv docs-early-access/assets/images assets/images/early-access
mv docs-early-access/content content/early-access
diff --git a/src/dev-toc/generate.ts b/src/dev-toc/generate.ts
index f883ccbbad96..3d7c16ffc1ec 100644
--- a/src/dev-toc/generate.ts
+++ b/src/dev-toc/generate.ts
@@ -1,14 +1,10 @@
-/**
- * @purpose Writer tool
- * @description Generate a local table of contents for the GitHub Docs website
- *
- * This script creates static HTML files for each documentation version, renders page titles
- * using Liquid templating, and opens the generated TOC in your browser for easy navigation
- * during development. Supports command-line options to specify which sections should be
- * open by default.
- *
- * Usage: tsx src/dev-toc/generate.ts [-o product-ids...]
- */
+// @purpose Writer tool
+// @description Generate a local table of contents for the GitHub Docs website
+//
+// Creates static HTML for each documentation version, renders Liquid page titles, and opens the
+// generated table of contents in your browser. Use -o product-ids... to open sections by default.
+//
+// Run with: tsx src/dev-toc/generate.ts [-o product-ids...]
import fs from 'fs'
import path from 'path'
diff --git a/src/dev-toc/layout.html b/src/dev-toc/layout.html
index 24d8fab8fccd..78c08dde5811 100644
--- a/src/dev-toc/layout.html
+++ b/src/dev-toc/layout.html
@@ -38,7 +38,6 @@ TOC for {{ allVersions[currentVersion].versio
{{ productPage.renderedFullTitle }}
- {% comment %} Unified nested rendering with depth control {% endcomment %}
{% if productPage.childPages and productPage.childPages.size > 0 %}
{% for l1 in productPage.childPages %}
diff --git a/src/early-access/middleware/early-access-links.ts b/src/early-access/middleware/early-access-links.ts
index a09dfdc939f5..b9ac7d0f7cbd 100644
--- a/src/early-access/middleware/early-access-links.ts
+++ b/src/early-access/middleware/early-access-links.ts
@@ -8,13 +8,11 @@ export default function earlyAccessContext(
res: Response,
next: NextFunction,
) {
- // Use req.pagePath instead of req.path because req.path is the path
- // normalized after "converting" that `/_next/data/...` path to the
- // equivalent path if it had *not* been a client-side routing fetch.
+ // handleNextDataPath sets converted routes in req.pagePath; req.path keeps the /_next/data URL.
const url = req.pagePath!.split('/').slice(2)
if (
!(
- // Is it `/early-access` or `/enterprise-cloud@latest/early-access`?
+ // Match /early-access and versioned /early-access routes.
(
(url.length === 2 && url[1] === 'early-access') ||
(url.length === 1 && url[0] === 'early-access')
@@ -45,7 +43,7 @@ export default function earlyAccessContext(
.sort()
.map((permalink) => `- [${permalink.title}](${permalink.href})`)
- // Only read by the separate EA repo, in local development.
+ // Only the separate early access repo reads this, in local development.
req.context.earlyAccessPageLinks = earlyAccessPageLinks.length
? earlyAccessPageLinks.join('\n')
: '_None for this version!_'
diff --git a/src/early-access/scripts/clone-locally b/src/early-access/scripts/clone-locally
index ab816c586dba..4564e5f83a04 100755
--- a/src/early-access/scripts/clone-locally
+++ b/src/early-access/scripts/clone-locally
@@ -5,7 +5,6 @@
set -e
-# Go up a directory
pushd .. > /dev/null
if [ -d "docs-early-access" ]; then
@@ -14,13 +13,10 @@ if [ -d "docs-early-access" ]; then
exit 0
fi
-# Clone the repo
git clone https://github.com/github/docs-early-access.git
-# Go back to the previous working directory
popd > /dev/null
-# Symlink the local docs-early-access repo into this repo
npm run symlink-from-local-repo -- -p ../docs-early-access
echo -e '\nDone!'
diff --git a/src/early-access/scripts/create-branch b/src/early-access/scripts/create-branch
index c5f6fb6fad46..456e98db95ae 100755
--- a/src/early-access/scripts/create-branch
+++ b/src/early-access/scripts/create-branch
@@ -5,7 +5,6 @@
set -e
-# Get current branch name
currentBranch=$(git rev-parse --abbrev-ref HEAD)
if [ $currentBranch == "main" ]; then
@@ -13,7 +12,6 @@ if [ $currentBranch == "main" ]; then
exit 0
fi
-# Go up a directory
pushd .. > /dev/null
if [ ! -d "docs-early-access" ]; then
@@ -22,17 +20,13 @@ if [ ! -d "docs-early-access" ]; then
exit 0
fi
-# Navigate to docs-early-access
cd docs-early-access
-# Check out main and update
git checkout main
git pull origin main
-# Create a branch with the current docs-internal branch name
git checkout -b $currentBranch
-# Go back to the previous working directory
popd > /dev/null
echo -e "\nDone! Created a branch called ${currentBranch}. Remember to commit your work in ../docs-early-access when you're ready."
diff --git a/src/early-access/scripts/merge-early-access.sh b/src/early-access/scripts/merge-early-access.sh
index 8c70e549dc4c..00df810ca60d 100755
--- a/src/early-access/scripts/merge-early-access.sh
+++ b/src/early-access/scripts/merge-early-access.sh
@@ -1,10 +1,6 @@
#!/usr/bin/env bash
-# [start-readme]
-#
-# This script takes docs-early-access files and merges them into docs-internal
-#
-# [end-readme]
+# Merges docs-early-access files into docs-internal.
mv docs-early-access/assets/images assets/images/early-access
mv docs-early-access/content content/early-access
diff --git a/src/early-access/scripts/migrate-early-access-product.ts b/src/early-access/scripts/migrate-early-access-product.ts
index ef7e6cf2ae6f..0dbedc8430ea 100644
--- a/src/early-access/scripts/migrate-early-access-product.ts
+++ b/src/early-access/scripts/migrate-early-access-product.ts
@@ -1,8 +1,4 @@
-// [start-readme]
-//
-// Move the files from an early-access product level docs set into an existing product.
-//
-// [end-readme]
+// Moves a product-level early access docs set into an existing product.
import fs from 'fs'
import path from 'path'
@@ -54,7 +50,7 @@ if (!filesToMigrate.length) {
const migratePath: string = path.posix.join(contentDir, newPathId)
-// Update the image and data refs in the to-be-migrated early access files BEFORE moving them.
+// Rewrite early access image and data refs before moving files.
try {
execFileSync('tsx', [
'src/early-access/scripts/update-data-and-image-paths.ts',
@@ -71,7 +67,7 @@ const variablesToMove: string[] = []
const reusablesToMove: string[] = []
const imagesToMove: string[] = []
-// Add redirects to and update frontmatter in the to-be-migrated early access files BEFORE moving them.
+// Apply redirects and frontmatter changes before moving files.
for (const filepath of filesToMigrate) {
const { content, data } = frontmatter(fs.readFileSync(filepath, 'utf8'))
const redirectString: string = filepath
@@ -86,7 +82,6 @@ for (const filepath of filesToMigrate) {
fs.writeFileSync(filepath, frontmatter.stringify(content || '', data))
}
- // Find the data files and images referenced in the early access files so we can move them over.
const dataRefs: string[] = content ? content.match(patterns.dataReference) || [] : []
const variables: string[] = dataRefs.filter((ref) => ref.includes('variables'))
const reusables: string[] = dataRefs.filter((ref) => ref.includes('reusables'))
@@ -97,7 +92,6 @@ for (const filepath of filesToMigrate) {
imagesToMove.push(...images)
}
-// Move the data files and images.
for (const varRef of Array.from(new Set(variablesToMove))) {
moveVariable(varRef)
}
@@ -108,10 +102,8 @@ for (const imageRef of Array.from(new Set(imagesToMove))) {
moveImage(imageRef)
}
-// Move the content files.
execFileSync('mv', [oldPath, migratePath])
-// Update the parent product TOC with the new child path.
const parentProductTocPath: string = path.posix.join(path.dirname(newPath), 'index.md')
const parentProductToc = frontmatter(fs.readFileSync(parentProductTocPath, 'utf-8'))
if (parentProductToc.data && Array.isArray(parentProductToc.data.children)) {
@@ -123,7 +115,6 @@ fs.writeFileSync(
frontmatter.stringify(parentProductToc.content || '', parentProductToc.data || {}),
)
-// Optionally, update the new product TOC with the new title.
if (program.opts().newTitle) {
const productTocPath: string = path.posix.join(newPath, 'index.md')
const productToc = frontmatter(fs.readFileSync(productTocPath, 'utf-8'))
@@ -137,7 +128,6 @@ if (program.opts().newTitle) {
)
}
-// Update internal links now that the files have been moved.
console.log('\nRunning script to update internal links...')
execFileSync('tsx', ['src/links/scripts/update-internal-links.ts'])
@@ -153,18 +143,15 @@ Please review all the changes in docs-internal and docs-early-access, especially
`)
function moveVariable(dataRef: string): void {
- // Get the data filepath from the data reference,
- // where the data reference looks like: {% data variables.foo.bar %}
- // and the data filepath looks like: data/variables/foo.yml with key of 'bar'.
+ // Variable refs like {% data variables.foo.bar %} map to data/variables/foo.yml plus key bar.
const variablePathArray: string[] =
dataRef
.match(/{% (?:data|indented_data_reference) (.*?) %}/)?.[1]
.split('.')
- // If early access is part of the path, remove it (since the path below already includes it)
+ // Remove early-access because the path already joins under data/early-access.
.filter((n) => n !== 'early-access') || []
- // In `variables.foo.bar` the last segment is the variable key.
- // Pop it off, leaving the filepath `variables/foo.yml`.
+ // The last segment is the variable key; the remaining segments form variables/foo.yml.
const variableKey: string = last(variablePathArray) as string
variablePathArray.pop()
@@ -218,14 +205,12 @@ function moveVariable(dataRef: string): void {
}
function moveReusable(dataRef: string): void {
- // Get the data filepath from the data reference,
- // where the data reference looks like: {% data reusables.foo.bar %}
- // and the data filepath looks like: data/reusables/foo/bar.md.
+ // Reusable refs like {% data reusables.foo.bar %} map to data/reusables/foo/bar.md.
const reusablePath: string =
dataRef
.match(/{% (?:data|indented_data_reference) (\S*?) .*%}/)?.[1]
.split('.')
- // If early access is part of the path, remove it (since the path below already includes it)
+ // Remove early-access because the path already joins under data/early-access.
.filter((n) => n !== 'early-access')
.join('/') || ''
@@ -254,7 +239,7 @@ function moveReusable(dataRef: string): void {
function moveImage(imageRef: string): void {
const imagePath: string = imageRef
.replace('/assets/images/', '')
- // If early access is part of the path, remove it (since the path below already includes it)
+ // Remove early-access because the path already joins under assets/images/early-access.
.replace('early-access', '')
const oldImagePath: string = path.posix.join(
diff --git a/src/early-access/scripts/symlink-from-local-repo.ts b/src/early-access/scripts/symlink-from-local-repo.ts
index 43ef6423ec9c..59040f0a295b 100644
--- a/src/early-access/scripts/symlink-from-local-repo.ts
+++ b/src/early-access/scripts/symlink-from-local-repo.ts
@@ -1,7 +1,5 @@
-/**
- * @purpose Writer tool
- * @description Create or destroy symlinks to your local docs-early-access checkout
- */
+// @purpose Writer tool
+// @description Create or destroy symlinks to your local docs-early-access checkout
import fs from 'fs'
import path from 'path'
@@ -64,7 +62,6 @@ const destinationDirsMap: Record = destinationDirNames.reduce(
{} as Record,
)
-// Remove all existing early access directories from this repo
for (const dirName of destinationDirNames) {
const destDir = destinationDirsMap[dirName]
fs.rmSync(destDir, { recursive: true, force: true })
@@ -75,7 +72,6 @@ if (unlink) {
process.exit(0)
}
-// Symlink the latest early access source directories into this repo
for (const dirName of destinationDirNames) {
if (!earlyAccessLocalRepoDir) continue
diff --git a/src/early-access/scripts/update-data-and-image-paths.ts b/src/early-access/scripts/update-data-and-image-paths.ts
index f1823f9e1187..c7220d4f0803 100644
--- a/src/early-access/scripts/update-data-and-image-paths.ts
+++ b/src/early-access/scripts/update-data-and-image-paths.ts
@@ -1,7 +1,5 @@
-/**
- * @purpose Writer tool
- * @description Add or remove "early-access" from data and image paths
- */
+// @purpose Writer tool
+// @description Add or remove "early-access" from data and image paths
import fs from 'fs'
import path from 'path'
@@ -45,7 +43,7 @@ let selectedFiles: string[] = allEarlyAccessFiles
if (earlyAccessPath) {
const contentFiles = allEarlyAccessFiles.filter((file) => file.includes(earlyAccessPath))
- // We also need to include any reusable files that are referenced in the selected content files.
+ // Include reusable files referenced by selected content files.
const referencedDataFiles: string[] = []
for (const file of contentFiles) {
const contents = fs.readFileSync(file, 'utf8')
diff --git a/src/early-access/scripts/what-docs-early-access-branch.ts b/src/early-access/scripts/what-docs-early-access-branch.ts
index fd69e85f1c1c..41e89a0ff5f9 100644
--- a/src/early-access/scripts/what-docs-early-access-branch.ts
+++ b/src/early-access/scripts/what-docs-early-access-branch.ts
@@ -16,9 +16,7 @@ async function main(): Promise {
const OUTPUT_KEY = 'branch'
- // If being run from a PR, this becomes 'my-cool-branch'.
- // If run on main, with the `workflow_dispatch` action for
- // example, the value becomes 'main'.
+ // Use the matching docs-early-access branch when it exists; 404 falls back to main.
const github = getOctokit(GITHUB_TOKEN)
for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
@@ -39,7 +37,7 @@ async function main(): Promise {
setOutput(OUTPUT_KEY, 'main')
return
}
- // Retry on network/server errors (5xx, timeouts, etc.)
+ // Retry any non-404 failure until MAX_RETRIES is reached.
if (attempt < MAX_RETRIES) {
console.warn(
`Attempt ${attempt}/${MAX_RETRIES} failed with error: ${err instanceof Error ? err.message : String(err)}. Retrying in ${RETRY_DELAY_SECONDS}s...`,
diff --git a/src/early-access/tests/early-access-unit.ts b/src/early-access/tests/early-access-unit.ts
index d133f1479a12..a5b267b1ca34 100644
--- a/src/early-access/tests/early-access-unit.ts
+++ b/src/early-access/tests/early-access-unit.ts
@@ -28,7 +28,7 @@ describeIfDocsEarlyAccess('early access rendering', () => {
test('404 if any other language than English', async () => {
for (const code of Object.keys(languages)) {
if (code === 'en') {
- // This is tested elsewhere
+ // English early access rendering has separate tests above.
continue
}
const res = await get(`/${code}${VALID_EARLY_ACCESS_URI}`)
diff --git a/src/eslint-rules/no-dangerously-set-inner-html/no-dangerously-set-inner-html.js b/src/eslint-rules/no-dangerously-set-inner-html/no-dangerously-set-inner-html.js
index 75b90dbc8b14..174e8a8856bf 100644
--- a/src/eslint-rules/no-dangerously-set-inner-html/no-dangerously-set-inner-html.js
+++ b/src/eslint-rules/no-dangerously-set-inner-html/no-dangerously-set-inner-html.js
@@ -15,17 +15,12 @@ module.exports = {
},
create(context) {
return {
- // Flag the JSX attribute form:
JSXAttribute(node) {
if (node.name && node.name.name === "dangerouslySetInnerHTML") {
context.report({ node, messageId: "noDanger" });
}
},
- // Flag the object-property form used when spreading props, e.g.
- // { dangerouslySetInnerHTML: { __html: html } }. Only object *expressions*
- // (constructing props) are unsafe; skip object *patterns* (destructuring
- // like `const { dangerouslySetInnerHTML, ...rest } = props`), which strip
- // the prop and are safe.
+ // Object expressions can build JSX-spread dangerouslySetInnerHTML; patterns only read props.
Property(node) {
if (!node.parent || node.parent.type !== "ObjectExpression") return;
const key = node.key;
@@ -38,9 +33,7 @@ module.exports = {
context.report({ node, messageId: "noDanger" });
}
},
- // Flag the assignment form, including the computed string-key bypass:
- // props.dangerouslySetInnerHTML = { __html: html }
- // props['dangerouslySetInnerHTML'] = { __html: html }
+ // Direct and computed assignments bypass JSX-attribute checks, so flag both forms.
AssignmentExpression(node) {
const left = node.left;
if (!left || left.type !== "MemberExpression") return;
diff --git a/src/eslint-rules/no-dangerously-set-inner-html/tests/no-dangerously-set-inner-html.ts b/src/eslint-rules/no-dangerously-set-inner-html/tests/no-dangerously-set-inner-html.ts
index 399ef0225838..c5a80d0189aa 100644
--- a/src/eslint-rules/no-dangerously-set-inner-html/tests/no-dangerously-set-inner-html.ts
+++ b/src/eslint-rules/no-dangerously-set-inner-html/tests/no-dangerously-set-inner-html.ts
@@ -21,7 +21,7 @@ describe('no-dangerously-set-inner-html', () => {
{ code: `const el = ((resolve) => {
releaseNavigation = resolve
@@ -261,24 +239,16 @@ test('sidebar highlights the clicked item optimistically while navigation is pen
await helloWorld.click()
- // While pending: the clicked link carries the optimistic visual marker, but the URL
- // and the semantic aria-current still reflect the (still-loaded) get-started page.
await expect(helloWorld).toHaveAttribute('data-pending', '')
await expect(helloWorld).not.toHaveAttribute('aria-current', 'page')
await expect(page).not.toHaveURL(/hello-world/)
- // Let the navigation finish: the marker gives way to a real aria-current.
releaseNavigation()
await expect(page).toHaveURL(/\/en\/get-started\/start-your-journey\/hello-world/)
await expect(helloWorld).toHaveAttribute('aria-current', 'page')
await expect(helloWorld).not.toHaveAttribute('data-pending', '')
- // A modifier-click (open in new tab) must NOT move the optimistic selection.
- // handleNavClick bails on modifier clicks, so pendingHref is never set: the current
- // page keeps its URL, its aria-current, and the clicked link gets no data-pending.
- // Use ControlOrMeta so the real "open in new tab" modifier is sent per-platform
- // (Ctrl on Linux/Windows CI, Meta on macOS). The click opens a background tab we
- // don't need to assert on; catch any popup so it doesn't leak.
+ // handleNavClick skips modifier clicks; ControlOrMeta must not set pendingHref. Close the popup.
page.on('popup', (popup) => popup.close())
await linkRewriting.click({ modifiers: ['ControlOrMeta'] })
await expect(linkRewriting).not.toHaveAttribute('data-pending', '')
@@ -290,18 +260,15 @@ test('press "/" to open the search overlay', async ({ page }) => {
await page.goto('/')
await turnOffExperimentsInPage(page)
- // Wait for the header search button to render, so the keydown listener is attached.
+ // The keydown listener attaches when the header search button renders.
await page.getByTestId('toggle-search').waitFor()
const searchInput = page.getByTestId('overlay-search-input')
- // The overlay (and its input) is not in the DOM until it's opened.
await expect(searchInput).toHaveCount(0)
- // Pressing "/" anywhere on the page opens the overlay and focuses the input.
await page.keyboard.press('/')
await expect(searchInput).toBeFocused()
- // Escape closes it again and returns focus to the same responsive trigger.
await page.keyboard.press('Escape')
await expect(searchInput).toHaveCount(0)
await expect(page.getByTestId('toggle-search')).toBeFocused()
@@ -317,7 +284,7 @@ test('"/" typed inside the search input is a literal slash', async ({ page }) =>
const searchInput = page.getByTestId('overlay-search-input')
await expect(searchInput).toBeFocused()
- // The "/" shortcut must not fire while typing in a field, so it is not swallowed.
+ // The slash shortcut must not fire while typing in a field.
await page.keyboard.type('a/b')
await expect(searchInput).toHaveValue('a/b')
})
@@ -352,11 +319,8 @@ test('open search, and perform a general search', async ({ page }) => {
await page.getByTestId('toggle-search').click()
await page.getByTestId('overlay-search-input').fill('serve playwright')
- // Wait for the results to load
- // NOTE: In the UI we wait for results to load before allowing "enter", because we don't want
- // to allow an unnecessary request when there are no search results. Easier to wait 1 second
+ // Wait 1 second for results to load, because the UI blocks submitting the query until then.
await page.waitForTimeout(1000)
- // Scroll down to "View all results" then press enter
await page.getByText('View more results').click()
await expect(page).toHaveURL(
@@ -364,7 +328,6 @@ test('open search, and perform a general search', async ({ page }) => {
)
await expect(page).toHaveTitle(/\d Search results for "serve playwright"/)
- // The first result should be "For Playwright"
await page.getByRole('link', { name: 'For Playwright' }).click()
await expect(page).toHaveURL(/\/get-started\/foo\/for-playwright$/)
@@ -379,13 +342,11 @@ test('open search, and select a general search article', async ({ page }) => {
await page.getByTestId('toggle-search').click()
await page.getByTestId('overlay-search-input').fill('serve playwright')
- // Let new suggestions load
const searchOverlay = page.getByTestId('general-autocomplete-suggestions')
await expect(searchOverlay.getByText('For Playwright')).toBeVisible()
await page.keyboard.press('ArrowDown')
await page.keyboard.press('Enter')
- // We should now be on the page for "For Playwright"
await expect(page).toHaveURL(/\/get-started\/foo\/for-playwright$/)
await expect(page).toHaveTitle(/For Playwright/)
})
@@ -403,7 +364,7 @@ test('open search, and get auto-complete results', async ({ page }) => {
let listItems = listGroup.locator('li')
await expect(listItems).toHaveCount(4)
- // Top queries from queries.json fixture's 'topQueries'
+ // The first list mirrors queries.json fixture topQueries.
let expectedTexts = [
'What is GitHub and how do I get started?',
'What is GitHub Copilot and how do I get started?',
@@ -422,7 +383,6 @@ test('open search, and get auto-complete results', async ({ page }) => {
await searchInput.fill('rest')
await page.waitForTimeout(1000)
- // Ask AI suggestions
listGroup = page.getByTestId('ai-autocomplete-suggestions')
listItems = listGroup.locator('li')
await expect(listItems).toHaveCount(3)
@@ -448,20 +408,14 @@ test('search from enterprise-cloud and filter by top-level Fooing', async ({ pag
await page.waitForTimeout(1000)
await page.getByText('View more results').click()
- // Now we're on the search results page, apply the filter
await page.getByText('Fooing (1)').click()
await page.getByRole('link', { name: 'Clear' }).click()
-
- // At the moment this test isn't great because it's not proving that
- // certain things cease to be visible, that was visible before. Room
- // for improvement!
})
test('404 page renders correctly', async ({ page }) => {
const response = await page.goto('/this-definitely-does-not-exist')
expect(response?.status()).toBe(404)
- // 404 pages now render a minimal HTML response
await expect(page.getByText('Page not found.')).toBeVisible()
})
@@ -507,7 +461,6 @@ test.describe('platform picker', () => {
await turnOffExperimentsInPage(page)
await page.getByTestId('platform-picker').getByRole('link', { name: 'Windows' }).click()
- // Return and now the cookie should start us off on Windows again
await page.goto('/get-started/liquid/platform-specific')
await expect(page.getByRole('heading', { name: /Windows 95/ })).toBeVisible()
await expect(page.getByRole('heading', { name: /Macintosh/ })).not.toBeVisible()
@@ -534,7 +487,7 @@ test.describe('tool picker', () => {
test('prefer default tool', async ({ page }) => {
await page.goto('/get-started/liquid/tool-specific')
- // defaultTool is set in the fixture frontmatter to webui
+ // The fixture frontmatter defaults defaultTool to webui.
await expect(page.getByText('This is webui content')).toBeVisible()
await expect(page.getByText('This is desktop content')).not.toBeVisible()
await expect(page.getByText('This is cli content')).not.toBeVisible()
@@ -545,7 +498,6 @@ test.describe('tool picker', () => {
await turnOffExperimentsInPage(page)
await page.getByTestId('tool-picker').getByRole('link', { name: 'Web browser' }).click()
- // Return and now the cookie should start us off with Web UI content again
await page.goto('/get-started/liquid/tool-specific')
await expect(page.getByText('This is cli content')).not.toBeVisible()
await expect(page.getByText('This is desktop content')).not.toBeVisible()
@@ -553,10 +505,9 @@ test.describe('tool picker', () => {
})
test('minitoc matches picker', async ({ page }) => {
- // See the note on the platform-specific version of this test: don't sit on
- // the drawer's exact reveal breakpoint.
+ // Avoid the drawer's exact reveal breakpoint.
await page.setViewportSize({ width: 1440, height: 900 })
- // default tool set to webui in fixture frontmatter
+ // The fixture frontmatter defaults defaultTool to webui.
await page.goto('/get-started/liquid/tool-specific')
await turnOffExperimentsInPage(page)
await expect(
@@ -616,9 +567,7 @@ test.describe('code tabs', () => {
test('navigate with side bar into article inside a subcategory inside a category', async ({
page,
}) => {
- // Our TreeView sidebar only shows "2 levels". If you click and expand
- // the category, you'll be able to see the subcategory and the article
- // within.
+ // The TreeView sidebar shows two levels until the category expands.
await page.goto('/actions')
await page.getByTestId('sidebar').getByText('Category', { exact: true }).click()
await page.getByTestId('sidebar').getByText('Subcategory').click()
@@ -645,7 +594,6 @@ test.describe('hover cards', () => {
await page.goto('/pages/quickstart')
await turnOffExperimentsInPage(page)
- // hover over a link and check for intro content from hovercard
await page
.locator('#article-contents')
.getByRole('link', { name: 'Start your journey' })
@@ -656,8 +604,6 @@ test.describe('hover cards', () => {
),
).toBeVisible()
- // now move the mouse away from hovering over the link, the hovercard should
- // no longer be visible
await page.mouse.move(0, 0)
await expect(
page.getByText(
@@ -665,38 +611,31 @@ test.describe('hover cards', () => {
),
).not.toBeVisible()
- // external links don't have a hovercard
await page.getByRole('link', { name: 'github.com/github/docs' }).hover()
await expect(page.getByTestId('popover')).not.toBeVisible()
- // links in the main navigation sidebar don't have a hovercard
await page.getByTestId('sidebar').getByRole('link', { name: 'Quickstart' }).hover()
await expect(page.getByTestId('popover')).not.toBeVisible()
- // links in the secondary minitoc sidebar don't have a hovercard
await page
.getByTestId('minitoc')
.getByRole('link', { name: 'Regular internal link', exact: true })
.hover()
await expect(page.getByTestId('popover')).not.toBeVisible()
- // links in the article intro have a hovercard
await page.locator('#article-intro').getByRole('link', { name: 'article intro link' }).hover()
await expect(page.getByText('You can use HubGit Pages to showcase')).toBeVisible()
- // this page's intro has two links; one in-page and one internal
await page.locator('#article-intro').getByRole('link', { name: 'another link' }).hover()
await expect(
page.getByText('Follow this Hello World exercise to get started with HubGit.'),
).toBeVisible()
- // same page anchor links have a hovercard
await page
.locator('#article-contents')
.getByRole('link', { name: 'introduction', exact: true })
.hover()
await expect(page.getByText('You can use HubGit Pages to showcase')).toBeVisible()
- // links with formatted text need to work too
await page.locator('#article-contents').getByRole('link', { name: 'Bold is strong' }).hover()
await expect(page.getByText('The most basic of fixture data for HubGit')).toBeVisible()
await page.locator('#article-contents').getByRole('link', { name: 'bar' }).hover()
@@ -707,7 +646,6 @@ test.describe('hover cards', () => {
await page.goto('/pages/quickstart')
await turnOffExperimentsInPage(page)
- // Simply putting focus on the link should not open the hovercard
await page
.locator('#article-contents')
.getByRole('link', { name: 'Start your journey' })
@@ -718,7 +656,6 @@ test.describe('hover cards', () => {
),
).not.toBeVisible()
- // Once a link has got focus, you can use Alt+ArrowUp to open the hovercard
await page.keyboard.press('Alt+ArrowUp')
await expect(
page.getByText(
@@ -738,7 +675,6 @@ test.describe('hover cards', () => {
await page.goto('/pages/quickstart')
await turnOffExperimentsInPage(page)
- // hover over a link and check for intro content from hovercard
await page
.locator('#article-contents')
.getByRole('link', { name: 'Start your journey' })
@@ -766,9 +702,7 @@ test.describe('test nav at different viewports', () => {
})
await page.goto('/get-started/foo/bar')
- // The Docs 2026 secondary bar leads with a Home crumb, then the full trail
- // 'Get started / Foo / Bar' (no hidden last crumb). The current page is
- // static text rather than a link, so only the three ancestors are links.
+ // Breadcrumbs include Home and the full trail; only the three ancestors are links.
expect(await page.getByTestId('breadcrumbs-bar').getByRole('link').all()).toHaveLength(3)
await expect(page.getByTestId('breadcrumbs-bar').locator('[aria-current="page"]')).toHaveText(
'Bar',
@@ -776,64 +710,51 @@ test.describe('test nav at different viewports', () => {
await expect(page.getByTestId('breadcrumbs-bar').getByText('Foo')).toBeVisible()
await expect(page.getByTestId('breadcrumbs-bar').getByText('Bar')).toBeVisible()
- // breadcrumbs show up in rest reference pages
await page.goto('/rest/actions/artifacts')
await expect(page.getByTestId('breadcrumbs-bar')).toBeVisible()
- // breadcrumbs show up in one of the pages that use the AutomatedPage
- // component (e.g. graphql, audit log). This one uses the webhooks
- // reference page here
+ // Webhooks renders through an AutomatedPage reference page, which shows breadcrumbs.
await page.goto('/webhooks/webhook-events-and-payloads')
await expect(page.getByTestId('breadcrumbs-bar')).toBeVisible()
})
test('mobile nav opens even when the desktop rail was collapsed', async ({ page }) => {
- // Collapse the desktop rail with both drawers out (xxl) so the persisted
- // `collapsed` state is set via the secondary-bar collapse toggle.
+ // At xxl with both drawers out, the secondary-bar collapse toggle persists collapsed.
page.setViewportSize({
width: 1400,
height: 700,
})
await page.goto('/get-started/foo/bar')
await page.getByTestId('sidebar-collapse-toggle').click()
- // With the rail collapsed the sidebar is not rendered on desktop.
await expect(page.getByTestId('sidebar')).toHaveCount(0)
- // Drop below lg (1012) where the inline mobile nav toggle lives (Docs 2026:
- // the lg–xxl range keeps the desktop collapse toggle instead). `collapsed`
- // persists across the resize.
+ // Below lg 1012px, the inline mobile nav toggle replaces the desktop collapse toggle.
page.setViewportSize({
width: 1000,
height: 700,
})
- // Opening the mobile nav must still render the doc-tree drawer. Before the
- // fix, `collapsed` short-circuited the sidebar to null while the open state
- // hid the content column, leaving a blank area with no drawer.
+ // Mobile nav must render the doc-tree drawer even with persisted collapsed state.
await page.getByTestId('sidebar-mobile-toggle').click()
await expect(page.getByTestId('sidebar')).toBeVisible()
- // Closing it restores the content column (main content visible again).
await page.getByTestId('sidebar-mobile-toggle').click()
await expect(page.locator('#main-content')).toBeVisible()
})
test('resizing from mobile to desktop closes the inline nav', async ({ page }) => {
- // Start below the lg (1012px) breakpoint where the inline mobile nav lives.
+ // Below lg 1012px, the inline mobile nav lives in the secondary bar.
await page.setViewportSize({
width: 1000,
height: 700,
})
await page.goto('/get-started/foo/bar')
- // Open the inline doc-tree nav from the secondary bar.
await page.getByTestId('sidebar-mobile-toggle').click()
const nav = page.locator('[data-container="nav"]')
await expect(nav).toHaveAttribute('data-mobile-open', 'true')
- // Resize up to the desktop breakpoint. The inline nav should close and the
- // fixed desktop rail (326px) should take over rather than the full-width
- // mobile markup persisting over the page.
+ // At 1400px, the desktop rail is 326px and replaces full-width mobile markup.
await page.setViewportSize({
width: 1400,
height: 700,
@@ -849,7 +770,6 @@ test.describe('test nav at different viewports', () => {
})
await page.goto('/get-started/foo/bar')
- // Both complete pickers are visible directly in the wide header.
await expect(
page.getByTestId('version-picker').getByText('Select your plan:', { exact: true }),
).toBeVisible()
@@ -863,7 +783,6 @@ test.describe('test nav at different viewports', () => {
await page.keyboard.press('Escape')
await expect(planMenu).not.toBeVisible()
- // The language picker is the same kind of nested dropdown as the plan one.
const languageButton = page.getByRole('button', {
name: 'Select language: current language is English',
})
@@ -887,15 +806,10 @@ test.describe('test nav at different viewports', () => {
})
await page.goto('/get-started/foo/bar')
- // breadcrumbs show up in the secondary bar; for this page we should have
- // a Home crumb plus 'Get started / Foo / Bar' — the last of which is the
- // current page, rendered as static text rather than a link.
await expect(page.getByTestId('breadcrumbs-bar')).toBeVisible()
expect(await page.getByTestId('breadcrumbs-bar').getByRole('link').all()).toHaveLength(3)
- // At lg+ (Docs 2026) the doc-tree rail is shown by default with the desktop
- // collapse toggle; the mobile inline-nav toggle is hidden. Clicking the
- // collapse toggle hides the rail.
+ // At lg+, the desktop rail shows and the inline-nav toggle hides.
await expect(page.getByTestId('sidebar')).toBeVisible()
await expect(page.getByTestId('sidebar-collapse-toggle')).toBeVisible()
await expect(page.getByTestId('sidebar-mobile-toggle')).toBeHidden()
@@ -945,8 +859,7 @@ test.describe('test nav at different viewports', () => {
await expect(languageMenu).not.toBeVisible()
await expect(page.getByTestId('header-signup')).toBeVisible()
- // The independent secondary-bar navigation is intentionally inert until the
- // modal header menu closes, then still expands the doc tree inline.
+ // The secondary-bar nav stays inert until the modal header menu closes.
await page.getByRole('button', { name: 'Close menu', exact: true }).click()
await expect(page.getByTestId('sidebar-mobile-toggle')).toBeVisible()
await page.getByTestId('sidebar-mobile-toggle').click()
@@ -998,13 +911,9 @@ test.describe('test nav at different viewports', () => {
})
test.describe('secondary-bar breadcrumb scroller', () => {
- // The secondary bar (and its breadcrumb scroller) only renders at wide
- // viewports, and the fixture trail is short enough to fit there, so we cap the
- // scroller width to force a deterministic overflow independent of title
- // lengths, then exercise the chevrons.
+ // Cap breadcrumb scroller width to force deterministic overflow.
test('chevrons scroll one crumb at a time instead of jumping to the ends', async ({ page }) => {
- // Smooth-scroll settle waits across several chevron clicks add up past the
- // default 5s cap.
+ // Several smooth-scroll waits can exceed the default 5s test cap.
test.setTimeout(20000)
page.setViewportSize({ width: 1300, height: 700 })
await page.goto('/get-started/foo/bar')
@@ -1015,11 +924,7 @@ test.describe('secondary-bar breadcrumb scroller', () => {
const scrollArea = page.locator('[data-search="breadcrumbs"]')
await expect(scrollArea).toBeVisible()
- // Force a deterministic overflow independent of title lengths: cap the
- // scroll region, drop the nav's min-width:100% (which otherwise stretches the
- // short fixture trail to fill the container so it never overflows), and pad
- // the crumbs so several are hidden at once — enough that a per-crumb nudge is
- // distinguishable from a jump to the end.
+ // Cap scroll width, remove nav min-width:100%, and pad crumbs to detect nudges.
await page.addStyleTag({
content: `
[data-search="breadcrumbs"] { max-width: 360px; }
@@ -1032,37 +937,28 @@ test.describe('secondary-bar breadcrumb scroller', () => {
const maxScrollOf = () => scrollArea.evaluate((el) => el.scrollWidth - el.clientWidth)
await expect.poll(maxScrollOf).toBeGreaterThan(0)
- // Anchor to the right end explicitly so we start from a known state: fully
- // scrolled right (current page visible), only the left chevron active.
+ // Start fully scrolled right so only the left chevron is active.
await scrollArea.evaluate((el) => el.scrollTo({ left: el.scrollWidth, behavior: 'instant' }))
const maxScroll = await maxScrollOf()
await expect.poll(scrollLeftOf).toBe(maxScroll)
const leftChevron = page.getByRole('button', { name: 'Scroll breadcrumbs left' })
const rightChevron = page.getByRole('button', { name: 'Scroll breadcrumbs right' })
- // At the right extreme the left chevron is active and the right one is hidden.
await expect(leftChevron).toBeVisible()
await expect(rightChevron).toBeHidden()
- // One left click nudges toward the start by a single crumb — it must move,
- // but must NOT jump all the way to 0 (the old behavior) while more than one
- // crumb is still hidden to the left.
+ // One left click must move without jumping to 0 while crumbs stay hidden left.
await leftChevron.click()
await expect.poll(scrollLeftOf).toBeLessThan(maxScroll)
const afterOneLeft = await scrollLeftOf()
expect(afterOneLeft).toBeGreaterThan(0)
- // The right chevron appears once we're no longer at the right extreme.
await expect(rightChevron).toBeVisible()
- // A right click walks back toward the current page by one crumb, not a full
- // jump back to the right extreme.
+ // Right click returns by one crumb, not a jump to the right extreme.
await rightChevron.click()
await expect.poll(scrollLeftOf).toBeGreaterThan(afterOneLeft)
- // Repeated left clicks eventually reach the start, which hides the left
- // chevron (canScrollLeft flips false). Drive off the chevron's own visibility
- // rather than an exact scrollLeft, since smooth scrolling can leave a
- // sub-pixel remainder.
+ // Drive off chevron visibility because smooth scrolling can leave sub-pixel scrollLeft.
for (let i = 0; i < 6 && (await leftChevron.isVisible()); i++) {
await leftChevron.click()
await page.waitForTimeout(200)
@@ -1073,16 +969,10 @@ test.describe('secondary-bar breadcrumb scroller', () => {
})
test.describe('anchor link scrolling', () => {
- // The doc-tree rail only renders at the xxl breakpoint (1400px) and up. Its
- // "centre the active item" effect used to call scrollIntoView, which scrolls
- // every scrollable ancestor including the document, so it undid the browser's
- // scroll to the #anchor and dumped the reader at the top of the article.
- // These tests only mean anything with the rail on screen.
+ // At xxl, centering the active doc-tree item can undo browser anchor scrolling.
const WIDE = { width: 1400, height: 720 }
- // The heading is offset from the top of the viewport by `scroll-margin-top`
- // (109px at xxl, see src/frame/stylesheets/scroll-top.scss). Allow slack for
- // rounding and sticky-header tweaks, but stay well clear of "not scrolled".
+ // scroll-margin-top is 109px at xxl; allow rounding and sticky-header slack, but reject an unscrolled page.
const expectScrolledToTarget = async (page: import('@playwright/test').Page) => {
const heading = page.locator('#target-heading')
await expect(heading).toBeVisible()
@@ -1096,10 +986,7 @@ test.describe('anchor link scrolling', () => {
await expect(page.getByTestId('sidebar')).toBeVisible()
await expectScrolledToTarget(page)
- // Guard the setup: the regression only shows when the rail has actually
- // scrolled its own container to centre the active item. If a fixture change
- // ever makes the rail short enough that it doesn't need to scroll, these
- // tests would keep passing while covering nothing — fail loudly instead.
+ // Fail if the fixture rail stops scrolling, because the test would cover nothing.
const railScrollTop = await page
.getByTestId('sidebar')
.evaluate((el) => el.closest('[role="region"]')!.scrollTop)
@@ -1135,8 +1022,7 @@ test.describe('survey', () => {
const surveyComment = 'This is a comment'
- // Important to set this up *before* interacting with the page
- // in case of possible race conditions.
+ // Install the route before interacting with the page to avoid event races.
await page.route('**/api/events', (route, request) => {
const postData = request.postData()
if (postData) {
@@ -1160,10 +1046,7 @@ test.describe('survey', () => {
}
}
}
- // At the time of writing you can't get the posted payload
- // when you use `navigator.sendBeacon(url, data)`.
- // So we can't make assertions about the payload.
- // See https://github.com/microsoft/playwright/issues/12231
+ // Chromium hides sendBeacon payloads from Playwright: https://github.com/microsoft/playwright/issues/12231
})
await page.addInitScript(() => {
@@ -1172,7 +1055,7 @@ test.describe('survey', () => {
await page.goto('/get-started/foo/for-playwright')
- // The label is visually an SVG. Finding it by its `for` value feels easier.
+ // The label renders as an SVG, so locate it by for=survey-yes.
await page.locator('[for=survey-yes]').click()
await expect(page.getByRole('button', { name: 'Cancel' })).toBeVisible()
await expect(page.getByRole('button', { name: 'Send' })).toBeVisible()
@@ -1181,7 +1064,6 @@ test.describe('survey', () => {
await page.locator('[name=survey-email]').click()
await page.locator('[name=survey-email]').fill('test@example.com')
await page.getByRole('button', { name: 'Send' }).click()
- // simulate sending an exit event to trigger sending all queued events
await page.evaluate(() => {
Object.defineProperty(document, 'visibilityState', {
configurable: true,
@@ -1193,11 +1075,7 @@ test.describe('survey', () => {
return new Promise((resolve) => setTimeout(resolve, 100))
})
- // Events:
- // 1. page view event when navigating to the page
- // 2. Survey thumbs up event
- // 3. Survey submit event
- // 4. Exit event
+ // fulfilled counts page view, survey thumbs up, survey submit, and exit events.
expect(fulfilled).toBe(1 + 1 + 1 + 1)
expect(hasSurveyPressedEvent).toBe(true)
expect(hasSurveySubmittedEvent).toBe(true)
@@ -1208,8 +1086,7 @@ test.describe('survey', () => {
let fulfilled = 0
let hasSurveyEvent = false
- // Important to set this up *before* interacting with the page
- // in case of possible race conditions.
+ // Install the route before interacting with the page to avoid event races.
await page.route('**/api/events', (route, request) => {
const postData = request.postData()
if (postData) {
@@ -1223,10 +1100,7 @@ test.describe('survey', () => {
}
}
}
- // At the time of writing you can't get the posted payload
- // when you use `navigator.sendBeacon(url, data)`.
- // So we can't make assertions about the payload.
- // See https://github.com/microsoft/playwright/issues/12231
+ // Chromium hides sendBeacon payloads from Playwright: https://github.com/microsoft/playwright/issues/12231
})
await page.addInitScript(() => {
@@ -1236,7 +1110,6 @@ test.describe('survey', () => {
await page.goto('/get-started/foo/for-playwright')
await page.locator('[for=survey-yes]').click()
- // simulate sending an exit event to trigger sending all queued events
await page.evaluate(() => {
Object.defineProperty(document, 'visibilityState', {
configurable: true,
@@ -1247,10 +1120,7 @@ test.describe('survey', () => {
document.dispatchEvent(new Event('visibilitychange'))
return new Promise((resolve) => setTimeout(resolve, 100))
})
- // Events:
- // 1. page view event when navigating to the page
- // 2. the thumbs up click
- // 3. the exit event
+ // fulfilled counts page view, thumbs up, and exit events.
expect(fulfilled).toBe(1 + 1 + 1)
expect(hasSurveyEvent).toBe(true)
@@ -1259,8 +1129,7 @@ test.describe('survey', () => {
})
test('vote on one page, then go to another and it should reset', async ({ page }) => {
- // Important to set this up *before* interacting with the page
- // in case of possible race conditions.
+ // Install the route before interacting with the page to avoid event races.
await page.route('**/api/events', (route) => {
route.fulfill({})
})
@@ -1284,12 +1153,10 @@ test.describe('survey', () => {
test.describe('rest API reference pages', () => {
test('REST actions', async ({ page }) => {
await page.goto('/rest')
- // Before using the sidebar, make sure the page has redirected to a
- // URL that has that `?apiVersion=` query parameter.
+ // Redirect must add the apiVersion query before sidebar navigation.
await expect(page).toHaveURL(/\/en\/rest\?apiVersion=/)
await page.getByTestId('sidebar').getByText('Actions').click()
- // Brand NavList renders leaf articles as links (not the label-associated
- // controls Primer used), so locate them by link role rather than getByLabel.
+ // Brand NavList renders leaf articles as links, not Primer's label-associated controls.
await page.getByTestId('sidebar').getByRole('link', { name: 'Artifacts' }).click()
await page
.getByTestId('sidebar')
@@ -1313,7 +1180,6 @@ test.describe('translations', () => {
await expect(page).toHaveURL('/ja')
await expect(page.getByRole('heading', { name: '日本 GitHub Docs' })).toBeVisible()
- // Having done this once, should now use a cookie to redirect back to Japanese
await page.goto('/')
await expect(page).toHaveURL('/ja')
})
@@ -1326,16 +1192,11 @@ test.describe('translations', () => {
await expect(page).toHaveURL('/ja/get-started/start-your-journey/hello-world')
await expect(page.getByRole('heading', { name: 'こんにちは World' })).toBeVisible()
- // Having done this once, should now use a cookie to redirect
- // back to Japanese.
- // Playwright will cache this redirect, so we need to add something
- // to "cache bust" the URL
+ // Bust the URL because Playwright caches the redirect back to Japanese.
const cb = `?cb=${Math.random()}`
await page.goto(`/get-started/start-your-journey/hello-world${cb}`)
await expect(page).toHaveURL(`/ja/get-started/start-your-journey/hello-world${cb}`)
- // If you go, with the Japanese cookie, to the English page directly,
- // it will offer a link to the Japanese URL in a banner.
await page.goto('/en/get-started/start-your-journey/hello-world')
await expect(page).toHaveURL('/ja/get-started/start-your-journey/hello-world')
})
@@ -1344,9 +1205,7 @@ test.describe('translations', () => {
test('open search, and ask Copilot (Ask AI) a question', async ({ page }) => {
test.skip(!SEARCH_TESTS, 'No local Elasticsearch, no tests involving search')
- // Mock the CSE Copilot endpoint
await page.route('**/api/ai-search/v1', async (route) => {
- // Simulate the streaming response from CSE Copilot
const mockResponse = `{"chunkType":"SOURCES","sources":[{"title":"Creating a new repository","index":"/en/get-started","url":"http://localhost:4000/en/get-started"}]}
{"chunkType":"MESSAGE_CHUNK","text":"Creating "}
@@ -1380,31 +1239,23 @@ test('open search, and ask Copilot (Ask AI) a question', async ({ page }) => {
await page.getByTestId('toggle-search').click()
await page.getByTestId('overlay-search-input').fill('How do I create a Repository?')
- // Pressing enter should ask AI the question
await page.keyboard.press('Enter')
- // Wait for the AI response to appear
await expect(page.getByText('Creating a repository on GitHub')).toBeVisible()
- // Verify that sources are displayed
await expect(page.getByText('Creating a new repository')).toBeVisible()
- // Verify the full response appears
await expect(page.getByText('something you should already know how to do')).toBeVisible()
- // Open the "Creating new repository" source link list item
- // Find the references section first
const aiReferencesSection = page.getByTestId('ai-references')
await expect(aiReferencesSection).toBeVisible()
- // Wait for the reference list to be populated
await expect(page.getByText('Creating a new repository')).toBeVisible()
})
test('open search, Ask AI returns 400 error and shows general search results', async ({ page }) => {
test.skip(!SEARCH_TESTS, 'No local Elasticsearch, no tests involving search')
- // Mock the CSE Copilot endpoint to return a 400 error
await page.route('**/api/ai-search/v1', async (route) => {
await route.fulfill({
status: 400,
@@ -1422,21 +1273,16 @@ test('open search, Ask AI returns 400 error and shows general search results', a
await page.getByTestId('toggle-search').click()
await page.getByTestId('overlay-search-input').fill('foo')
- // Pressing enter should trigger Ask AI, get 400 error, and show general search results
await page.keyboard.press('Enter')
- // Wait for the general search results to appear inside the overlay's suggestions
- // group. These render as ActionList items (buttons), so scope the lookup to the
- // group rather than matching page-level links of the same name.
+ // Search suggestions render as ActionList buttons, so scope Foo and Bar to the suggestion group.
const generalSuggestions = page.getByTestId('general-autocomplete-suggestions')
await expect(generalSuggestions.getByRole('button', { name: 'Foo' })).toBeVisible()
await expect(generalSuggestions.getByRole('button', { name: 'Bar' })).toBeVisible()
- // Wait for the AI error message to appear
- // This is a canned response for the 400 error
- await page.waitForTimeout(1000) // Wait for the AI error message to appear
+ // Wait for the canned 400 response before checking the paragraph.
+ await page.waitForTimeout(1000)
- // Verify the AI error message appears (canned response for 400 error)
await expect(
page
.getByRole('paragraph')
@@ -1445,7 +1291,6 @@ test('open search, Ask AI returns 400 error and shows general search results', a
),
).toBeVisible()
- // Verify general search results appear above the AI section
const searchResults = page.getByTestId('general-autocomplete-suggestions')
const aiSection = page.locator('#ask-ai-result-container')
@@ -1460,13 +1305,11 @@ test.describe('LandingCarousel component', () => {
const carousel = page.locator('[data-testid="landing-carousel"]')
await expect(carousel).toBeVisible()
- // Check that article cards are present. Brand Card renders each card's title
- // as an (Card.Heading) wrapping a stretched , so target the heading.
+ // Brand Card renders each card title as h3 Card.Heading around a stretched link.
const items = page.locator('[data-testid="carousel-items"]')
const cardHeadings = items.locator('h3')
await expect(cardHeadings.first()).toBeVisible()
- // Verify cards have real titles (not "Unknown Article" when article not found)
await expect(cardHeadings.first()).not.toHaveText('Unknown Article')
})
@@ -1477,15 +1320,13 @@ test.describe('LandingCarousel component', () => {
const carousel = page.locator('[data-testid="landing-carousel"]')
await expect(carousel).toBeVisible()
- // Should show 3 cards on desktop
const cards = carousel.locator('a')
await expect(cards).toHaveCount(3)
- // Check for navigation buttons if there are more than 3 articles
const nextButton = carousel.getByRole('button', { name: 'Next articles' })
if (await nextButton.isVisible()) {
const prevButton = carousel.getByRole('button', { name: 'Previous articles' })
- await expect(prevButton).toBeDisabled() // Should be disabled on first page
+ await expect(prevButton).toBeDisabled()
await expect(nextButton).toBeEnabled()
}
})
@@ -1497,7 +1338,6 @@ test.describe('LandingCarousel component', () => {
const carousel = page.locator('[data-testid="landing-carousel"]')
await expect(carousel).toBeVisible()
- // Should show 1 card on mobile
const cards = carousel.locator('a')
await expect(cards).toHaveCount(1)
})
@@ -1507,36 +1347,32 @@ test.describe('Multi-carousel support', () => {
test('displays multiple carousels from carousels frontmatter', async ({ page }) => {
await page.goto('/get-started/multi-carousel')
- // Should have multiple carousels rendered
const carousels = page.locator('[data-testid="landing-carousel"]')
const carouselCount = await carousels.count()
- // We defined exactly 2 carousels in the frontmatter
+ // Frontmatter defines exactly two carousels.
expect(carouselCount).toBe(2)
})
test('carousel with matching ui.yml key displays translated title', async ({ page }) => {
await page.goto('/get-started/multi-carousel')
- // The "recommended" carousel should show "Recommended" title from ui.yml
+ // The recommended carousel title comes from ui.yml.
const carouselHeadings = page.locator('[data-testid="landing-carousel"] h2')
const headingTexts = await carouselHeadings.allTextContents()
- // Check that at least one heading has "Recommended"
expect(headingTexts.some((text) => text.includes('Recommended'))).toBe(true)
})
test('carousel without matching ui.yml key renders without title', async ({ page }) => {
await page.goto('/get-started/multi-carousel')
- // The "titleTwoNoMatchingUiYml" carousel should not have a visible heading
- // or the heading element should be empty/not exist for that carousel
+ // A carousel without a matching ui.yml key has no heading element.
const carouselHeadings = page.locator('[data-testid="landing-carousel"] h2')
const headingTexts = await carouselHeadings.allTextContents()
- // The raw key "titleTwoNoMatchingUiYml" should NOT appear as a heading
- // (the component should not show the key as fallback)
+ // titleTwoNoMatchingUiYml must not render as a fallback heading.
expect(headingTexts.some((text) => text === 'titleTwoNoMatchingUiYml')).toBe(false)
})
@@ -1546,10 +1382,8 @@ test.describe('Multi-carousel support', () => {
const carousels = page.locator('[data-testid="landing-carousel"]')
const count = await carousels.count()
- // We have 2 carousels: "recommended" and "titleTwoNoMatchingUiYml"
expect(count).toBe(2)
- // Count carousels that have h2 elements
let carouselsWithHeadings = 0
for (let i = 0; i < count; i++) {
const carousel = carousels.nth(i)
@@ -1559,11 +1393,9 @@ test.describe('Multi-carousel support', () => {
}
}
- // Only 1 carousel should have a heading (recommended has ui.yml entry)
- // titleTwoNoMatchingUiYml should NOT have an h2 element at all
+ // Only recommended has a ui.yml entry, so titleTwoNoMatchingUiYml must not render an h2.
expect(carouselsWithHeadings).toBe(1)
- // Verify the specific titles that should be visible
const visibleHeadings = await carousels.locator('h2').allTextContents()
expect(visibleHeadings).toContain('Recommended')
expect(visibleHeadings).not.toContain('titleTwoNoMatchingUiYml')
@@ -1575,7 +1407,6 @@ test.describe('Multi-carousel support', () => {
const carousels = page.locator('[data-testid="landing-carousel"]')
const count = await carousels.count()
- // Each carousel should have at least one article
for (let i = 0; i < count; i++) {
const carousel = carousels.nth(i)
const articles = carousel.locator('[data-testid="carousel-items"] a')
@@ -1592,14 +1423,12 @@ test.describe('Journey Tracks', () => {
const journeyTracks = page.locator('[data-testid="journey-tracks"]')
await expect(journeyTracks).toBeVisible()
- // Check that at least one track is displayed
const tracks = page.locator('[data-testid="journey-track"]')
await expect(tracks.first()).toBeVisible()
- // Verify track has proper structure
const firstTrack = tracks.first()
- await expect(firstTrack.locator('h2')).toBeVisible() // Track title
- await expect(firstTrack.locator('p')).toBeVisible() // Track description
+ await expect(firstTrack.locator('h2')).toBeVisible()
+ await expect(firstTrack.locator('p')).toBeVisible()
})
test('track expansion and collapse functionality', async ({ page }) => {
@@ -1608,7 +1437,6 @@ test.describe('Journey Tracks', () => {
const firstTrack = page.locator('[data-testid="journey-track"]').first()
const expandButton = firstTrack.locator('summary')
- // Initially collapsed
const articlesList = firstTrack.locator('[data-testid="journey-articles"]')
await expect(articlesList).not.toBeVisible()
@@ -1630,7 +1458,6 @@ test.describe('Journey Tracks', () => {
await expandButton.click()
- // Click on first article
const firstArticle = firstTrack.locator('[data-testid="journey-articles"] li a').first()
await expect(firstArticle).toBeVisible()
@@ -1646,7 +1473,7 @@ test.describe('Journey Tracks', () => {
const expandButton = firstTrack.locator('summary')
await expandButton.click()
- // article links should preserve the language and version
+ // Article links preserve language and version.
const firstArticle = firstTrack.locator('[data-testid="journey-articles"] li a').first()
const href = await firstArticle.getAttribute('href')
@@ -1659,7 +1486,6 @@ test.describe('Journey Tracks', () => {
const tracks = page.locator('[data-testid="journey-track"]')
- // Check that liquid templates are rendered (no raw template syntax visible)
const trackContent = await tracks.first().textContent()
expect(trackContent).not.toContain('{{')
expect(trackContent).not.toContain('}}')
@@ -1670,21 +1496,18 @@ test.describe('Journey Tracks', () => {
test('renders the single-track journey landing path', async ({ page }) => {
await page.goto('/get-started/test-journey-single')
- // single-track pages use the simplified heading + guide list, not the numbered cards
+ // Single-track pages render the simplified heading and guide list instead of numbered cards.
const singleTrack = page.locator('[data-testid="journey-single-track"]')
await expect(singleTrack).toBeVisible()
await expect(page.locator('[data-testid="journey-tracks"]')).toHaveCount(0)
- // heading is present
await expect(singleTrack.locator('h2')).toBeVisible()
- // guide list renders its article links
const guides = singleTrack.locator('[data-testid="journey-articles"] li a')
await expect(guides.first()).toBeVisible()
expect(await guides.count()).toBeGreaterThan(0)
- // without a surrounding card, the list must sit flush with the heading
- // rather than picking up the card's inset
+ // Without a card, the guide list sits flush with the heading instead of inheriting inset.
const listPaddingLeft = await singleTrack
.locator('[data-testid="journey-articles"]')
.evaluate((el) => getComputedStyle(el).paddingLeft)
@@ -1692,21 +1515,14 @@ test.describe('Journey Tracks', () => {
})
test('journey navigation components show on article pages', async ({ page }) => {
- // go to an article that's part of a journey track
await page.goto('/get-started/start-your-journey/hello-world')
- // The journey footer "Up next" nav should be visible. (The Docs 2026 redesign
- // removed the sidebar journey card; next-step info now lives in the bottom
- // pager + the in-panel "Up next" section.)
+ // Journey next-step info shows in the bottom pager and the right-rail Up next section.
const journeyNav = page.locator('[data-testid="journey-track-nav"]')
await expect(journeyNav).toBeVisible()
})
- // Restores the coverage the Docs 2026 migration dropped along with the sidebar
- // journey card: `alternativeNextStep` and its AUTOTITLE resolution now render
- // in the right-rail "Up next" section instead. That section rides the drawer's
- // reveal breakpoint, so it needs a viewport inside the drawer range and a
- // fixture long enough to keep the bottom pager outside the viewport.
+ // A drawer-range viewport shows alternativeNextStep and AUTOTITLE in Up next; the long fixture hides the pager.
test('up next displays branching text when present', async ({ page }) => {
await page.setViewportSize({ width: 1440, height: 900 })
await page.goto('/get-started/foo/journey-test-article')
@@ -1716,7 +1532,7 @@ test.describe('Journey Tracks', () => {
const upNext = page.getByTestId('up-next')
await expect(upNext).toBeVisible()
- // Branching text should be rendered with its markdown link resolved
+ // Branching text renders after resolving its markdown link.
await expect(upNext).toContainText('Want to skip ahead?')
await expect(upNext).not.toContainText('AUTOTITLE')
@@ -1758,7 +1574,6 @@ test.describe('Journey Tracks', () => {
const journeyNav = page.locator('[data-testid="journey-track-nav"]')
await expect(journeyNav).toBeVisible()
- // Link should display the next track's title and go to its first article
const nextTrackLink = journeyNav.locator('a').filter({ hasText: 'Advanced topics' })
await expect(nextTrackLink).toBeVisible()
@@ -1768,9 +1583,7 @@ test.describe('Journey Tracks', () => {
})
test.describe('Docs 2026 in-article navigation', () => {
- // Below the drawer's reveal breakpoint the right-rail "In this article" panel
- // is hidden and the collapsed control in the secondary bar is the ONLY
- // mini-TOC — the common case for most readers — so it needs its own coverage.
+ // Below the drawer breakpoint, the secondary-bar mini-TOC is the only in-page control.
test('the collapsed "In this article" menu navigates below the drawer breakpoint', async ({
page,
}) => {
@@ -1780,7 +1593,6 @@ test.describe('Docs 2026 in-article navigation', () => {
const subBar = page.getByTestId('overview-subbar')
await expect(subBar).toBeVisible()
- // The full drawer must not also be showing at this width.
await expect(page.getByTestId('minitoc')).toBeHidden()
await subBar.getByRole('button').click()
@@ -1794,11 +1606,7 @@ test.describe('Docs 2026 in-article navigation', () => {
expect(page.url()).toContain(href)
})
- // Regression guard. Platform/tool-gated headings stay in the DOM with the
- // `hidden` attribute, so they measure as an all-zero rect. Before
- // useActiveSection filtered by the selection, such a heading always satisfied
- // the "scrolled past" threshold, so the collapsed control could end up
- // labelled with a section belonging to a platform the reader had not chosen.
+ // useActiveSection filters hidden platform/tool headings because they have zero rects.
test('the collapsed menu is never labelled with a hidden platform section', async ({ page }) => {
await page.setViewportSize({ width: 1100, height: 900 })
await page.goto('/get-started/liquid/platform-specific?platform=windows')
@@ -1808,7 +1616,6 @@ test.describe('Docs 2026 in-article navigation', () => {
await expect(trigger).toBeVisible()
await expect(trigger).not.toContainText('Macintosh')
- // Scroll past the first heading so an active section is actually resolved.
await page.mouse.wheel(0, 2000)
await expect(trigger).not.toContainText('Macintosh')
})
@@ -1818,8 +1625,6 @@ test.describe('LandingArticleGridWithFilter component', () => {
test('displays article grid with filter controls', async ({ page }) => {
await page.goto('/get-started/article-grid-discovery')
- // Check that the main components are visible, title, categories drop
- // down, search input.
const articleGrid = page.getByTestId('article-grid')
await expect(articleGrid).toBeVisible()
@@ -1842,14 +1647,11 @@ test.describe('LandingArticleGridWithFilter component', () => {
const articleGrid = page.getByTestId('article-grid')
await expect(articleGrid).toBeVisible()
- // Check that article cards are present and they have expected structure
- // by checking the first card.
const articleCards = articleGrid.getByTestId('article-card')
await expect(articleCards.first()).toBeVisible()
const firstCard = articleCards.first()
- // Brand Card renders the title as an (Card.Heading) wrapping a
- // stretched , and the intro as a Card.Description .
+ // Brand Card renders titles as h3 Card.Heading links and intros as Card.Description paragraphs.
const titleLink = firstCard.locator('h3 a')
await expect(titleLink).toBeVisible()
@@ -1858,8 +1660,6 @@ test.describe('LandingArticleGridWithFilter component', () => {
const introText = await intro.textContent()
expect(introText).toBeTruthy()
- // Card should have categories, title, and intro, just check the card has
- // some text
const cardText = await firstCard.textContent()
expect(cardText).toBeTruthy()
expect(cardText!.length).toBeGreaterThan(0)
@@ -1868,27 +1668,23 @@ test.describe('LandingArticleGridWithFilter component', () => {
test('category filtering works correctly', async ({ page }) => {
await page.goto('/get-started/article-grid-discovery')
- // Check that category dropdown button exists and is clickable
const categoryDropdown = page.getByRole('button').filter({ hasText: 'All categories' })
await expect(categoryDropdown).toBeVisible()
- // Initially should show all articles (4 total in our fixtures)
+ // The fixture starts with four articles.
const articleGrid = page.getByTestId('article-grid')
await expect(articleGrid).toBeVisible()
const allArticleCards = articleGrid.getByTestId('article-card')
await expect(allArticleCards).toHaveCount(4)
- // Click the dropdown and the 'Testing' category
await categoryDropdown.click()
const testingOption = page.getByText('Testing', { exact: true }).last()
await expect(testingOption).toBeVisible()
await testingOption.click()
- // After filtering by Testing category, should show only 1 article based
- // on our fixtures.
+ // Filtering by Testing leaves one fixture article.
await expect(allArticleCards).toHaveCount(1)
- // Verify the filtered article contains "Testing" somewhere in its markup
const remainingCard = allArticleCards.first()
await expect(remainingCard).toContainText('Testing')
})
@@ -1899,18 +1695,17 @@ test.describe('LandingArticleGridWithFilter component', () => {
const searchInput = page.getByPlaceholder('Search articles')
await expect(searchInput).toBeVisible()
- // Initially should show all articles (4 total in our fixtures)
+ // The fixture starts with four articles.
const articleGrid = page.getByTestId('article-grid')
await expect(articleGrid).toBeVisible()
const articleCards = articleGrid.getByTestId('article-card')
await expect(articleCards).toHaveCount(4)
- // Search for "Grid" - based on our fixtures, multiple articles should have "Grid" in their names
+ // Multiple fixture article names contain Grid.
await searchInput.fill('Grid')
await expect(articleCards.first()).toBeVisible()
- // Verify that the remaining articles contain "Grid" in their content
const remainingCount = await articleCards.count()
expect(remainingCount).toBeGreaterThan(0)
for (let i = 0; i < remainingCount; i++) {
@@ -1925,44 +1720,33 @@ test.describe('LandingArticleGridWithFilter component', () => {
const searchInput = page.getByPlaceholder('Search articles')
await expect(searchInput).toBeVisible()
- // Search for a term that definitely won't match any articles, should show
- // no article cards
await searchInput.fill('noSuchArticles')
const articleGrid = page.getByTestId('article-grid')
await expect(articleGrid).toBeVisible()
const articleCards = articleGrid.getByTestId('article-card')
await expect(articleCards).toHaveCount(0)
- // Should show "no articles found" message as well
const noResultsMessage = page.getByTestId('no-articles-message')
await expect(noResultsMessage).toBeVisible()
await expect(noResultsMessage).toHaveText('No articles found matching your criteria.')
})
test('responsive behavior on different screen sizes', async ({ page }) => {
- // Super basic test, just make sure the article grid is visible on
- // different viewports sizes
-
- // Test desktop view (3 columns)
await page.setViewportSize({ width: 1200, height: 800 })
await page.goto('/get-started/article-grid-discovery')
const articleGrid = page.getByTestId('article-grid')
await expect(articleGrid).toBeVisible()
- // Test tablet view (2 columns)
await page.setViewportSize({ width: 768, height: 1024 })
- await page.waitForTimeout(100) // Brief wait for responsive changes
+ await page.waitForTimeout(100)
await expect(articleGrid).toBeVisible()
- // Test mobile view (1 column)
await page.setViewportSize({ width: 375, height: 667 })
- await page.waitForTimeout(100) // Brief wait for responsive changes
+ await page.waitForTimeout(100)
await expect(articleGrid).toBeVisible()
})
test('works with bespoke landing page', async ({ page }) => {
- // Other grid tests use the discovery landing page, bespoke pages are
- // similar so just do a quick check.
await page.goto('/get-started/article-grid-bespoke')
const articleGrid = page.getByTestId('article-grid')
@@ -1970,10 +1754,7 @@ test.describe('LandingArticleGridWithFilter component', () => {
})
test('card is keyboard-navigable via Enter (client-side)', async ({ page }) => {
- // The brand Card renders a native stretched anchor; a synthetic click from
- // pressing Enter on that anchor must bubble to the card's onClick handler so
- // keyboard users get the same client-side SPA navigation as mouse users.
- // Guards against a regression if the click-intercept logic is refactored.
+ // Brand Card's stretched anchor must bubble keyboard clicks for client-side navigation.
await page.goto('/get-started/article-grid-discovery')
const articleGrid = page.getByTestId('article-grid')
@@ -1983,8 +1764,7 @@ test.describe('LandingArticleGridWithFilter component', () => {
const href = await firstCardLink.getAttribute('href')
expect(href).toBeTruthy()
- // Mark the current document so we can prove navigation was client-side
- // (no full page reload): a hard navigation would wipe this window property.
+ // A hard navigation would clear this window marker; client-side navigation preserves it.
await page.evaluate(() => {
;(window as unknown as { __spaMarker?: boolean }).__spaMarker = true
})
@@ -2000,20 +1780,16 @@ test.describe('LandingArticleGridWithFilter component', () => {
})
test('bespoke landing page does not show duplicate articles', async ({ page }) => {
- // The bespoke fixture lists individual articles AND their parent group
- // as children, which would cause duplicates without deduplication.
+ // Bespoke fixtures list articles and their parent group, so deduplication prevents duplicates.
await page.goto('/get-started/article-grid-bespoke')
const articleGrid = page.getByTestId('article-grid')
await expect(articleGrid).toBeVisible()
const articleCards = articleGrid.getByTestId('article-card')
- // There are 4 unique articles across grid-category-one (2) and grid-category-two (2).
- // Even though grid-article-one and grid-article-two are listed both individually
- // and as children of grid-category-one, they should appear only once each.
+ // Four unique articles remain after deduplicating grid-article-one and grid-article-two.
await expect(articleCards).toHaveCount(4)
- // Verify no duplicate titles by collecting all card titles
const titles: string[] = []
const count = await articleCards.count()
for (let i = 0; i < count; i++) {
@@ -2027,19 +1803,16 @@ test.describe('LandingArticleGridWithFilter component', () => {
test.describe('Non-child page resolution', () => {
test('category page with local children renders properly', async ({ page }) => {
- // The local-category has local children (local-article-one, local-article-two)
- // and an external article reference via children frontmatter
+ // local-category mixes local-article-one, local-article-two, and an external frontmatter child.
await page.goto('/get-started/non-child-resolution/local-category')
- // Should have a title
await expect(page).toHaveTitle(/Local category test/)
- // The page should load without errors and have main content
await expect(page.locator('main')).toBeVisible()
})
test('cross-product children page loads correctly', async ({ page }) => {
- // The articles-only fixture now uses /content/ prefix in children for cross-product paths
+ // The articles-only fixture prefixes cross-product children with /content/.
await page.goto('/get-started/non-child-resolution/articles-only')
await expect(page).toHaveTitle(/Cross-product children test/)
@@ -2047,7 +1820,7 @@ test.describe('Non-child page resolution', () => {
})
test('children-only page with /content/ path loads correctly', async ({ page }) => {
- // The children-only fixture uses /content/ prefix for cross-product paths
+ // The children-only fixture prefixes cross-product children with /content/.
await page.goto('/get-started/non-child-resolution/children-only')
await expect(page).toHaveTitle(/Children only test/)
@@ -2062,20 +1835,19 @@ test.describe('Non-child page resolution', () => {
})
test('versioned cross-product children - fpt shows only fpt article', async ({ page }) => {
- // In fpt version, only the only-fpt article should be available
+ // In fpt, only only-fpt is available.
await page.goto('/get-started/non-child-resolution/versioned-cross-product')
await expect(page).toHaveTitle(/Versioned cross-product test/)
await expect(page.locator('main')).toBeVisible()
- // Check TOC has the fpt-only article
const tocLinks = page.locator('[data-testid="table-of-contents"] a')
await expect(tocLinks).toHaveCount(1)
await expect(tocLinks.first()).toHaveAttribute('href', /only-fpt/)
})
test('versioned cross-product children - ghec shows ghec articles', async ({ page }) => {
- // In ghec version, only-ghec and only-ghec-and-ghes should be available
+ // In ghec, only-ghec and only-ghec-and-ghes are available.
await page.goto(
'/enterprise-cloud@latest/get-started/non-child-resolution/versioned-cross-product',
)
@@ -2083,58 +1855,46 @@ test.describe('Non-child page resolution', () => {
await expect(page).toHaveTitle(/Versioned cross-product test/)
await expect(page.locator('main')).toBeVisible()
- // Check TOC has ghec articles (only-ghec and only-ghec-and-ghes)
const tocLinks = page.locator('[data-testid="table-of-contents"] a')
await expect(tocLinks).toHaveCount(2)
})
test('cross-product children excluded from sidebar in Japanese translation', async ({ page }) => {
- // The Japanese translation should work with cross-product children
+ // Japanese translations work with cross-product children.
await page.goto('/ja/get-started/non-child-resolution')
- // Verify page loads correctly with Japanese site context
- // Note: The title may not be fully translated in test fixtures, but the page should render
+ // Fixture titles can be partly untranslated, but Japanese site context must render.
await expect(page).toHaveTitle(/GitHub Docs/)
await expect(page.locator('main')).toBeVisible()
-
- // Verify page loads correctly - the cross-product children don't prevent the page from working
- // The detailed sidebar filtering is tested by the survey test which verifies no duplicate entries
})
})
test.describe('copy as markdown button', () => {
- // The article-body fetch backing this button is served for this fixture page
- // (see src/fixtures/tests/api-article-body.ts), so the copy path succeeds.
+ // api-article-body.ts serves this fixture's article-body fetch, so the copy path succeeds.
const articlePath = '/en/get-started/start-your-journey/api-article-body-test-page'
test('shows a checkmark after a successful copy', async ({ page, context }) => {
- // The click handler writes the article markdown to the clipboard.
await context.grantPermissions(['clipboard-read', 'clipboard-write'])
await page.goto(articlePath)
await turnOffExperimentsInPage(page)
- // `exact` matters: accessible-name matching is substring-based, so a bare
- // 'Copy markdown' also matches the code-block copy buttons that articles
- // with a ```markdown fence render ('Copy Markdown code to clipboard').
+ // Accessible-name matching treats names as substrings, so exact avoids code-block copy buttons.
const copyButton = page.getByRole('button', { name: 'Copy markdown', exact: true })
await expect(copyButton).toHaveCount(1)
await expect(copyButton).toBeVisible()
- // At rest the button is text-only — no icon at all. The checkmark below is
- // purely the success state.
+ // At rest the button is text-only; the checkmark is only the success state.
await expect(copyButton.locator('svg')).toHaveCount(0)
await copyButton.click()
- // After a successful copy, a checkmark appears...
await expect(copyButton.locator('.octicon-check')).toBeVisible()
- // ...and the article markdown lands on the clipboard.
const clipboardText = await page.evaluate(() => navigator.clipboard.readText())
expect(clipboardText).toContain('About GitHub')
- // The checkmark is temporary and clears again (2s timeout).
+ // The success checkmark clears after the 2s timeout.
await expect(copyButton.locator('.octicon-check')).toHaveCount(0, { timeout: 5000 })
})
})
diff --git a/src/frame/middleware/README.md b/src/frame/middleware/README.md
index e3f8c2b279f3..63e5e757e193 100644
--- a/src/frame/middleware/README.md
+++ b/src/frame/middleware/README.md
@@ -3,3 +3,15 @@
Each file in this directory exports an Express Middleware function.
For more info, see https://expressjs.com/en/guide/using-middleware.html
+
+## Mock Virtual Assistant portal
+
+`mock-va-portal.ts` lets you test the Virtual Assistant integration without access to a staging portal. The production portal rejects `localhost:4000` because it is hardened to `https://docs.github.com`.
+
+To test locally:
+
+1. Add `SUPPORT_PORTAL_URL=http://localhost:4000` to your `.env` file.
+2. Run `npm run dev`.
+3. Navigate to a page listed in the `PagePathToVaFlowMapping` object in `ArticleContext`.
+
+This mock is not secure. Use it only for local development.
diff --git a/src/frame/middleware/abort.ts b/src/frame/middleware/abort.ts
index e9f9496578ed..0e98af463e1a 100644
--- a/src/frame/middleware/abort.ts
+++ b/src/frame/middleware/abort.ts
@@ -14,18 +14,14 @@ class AbortError extends Error {
}
export default function abort(req: ExtendedRequest, res: Response, next: NextFunction) {
- // If the client aborts the connection, send an error
req.once('aborted', () => {
- // ignore aborts from next, usually has to do with webpack-hmr
+ // Ignore _next aborts, which usually come from webpack HMR.
if (req.path.startsWith('/_next')) {
return
}
- // NOTE: Node.js will also automatically set `req.aborted = true`
const incrementTags = []
- // Be careful with depending on attributes set on the `req` because
- // under certain conditions the contextualizers might not yet have
- // had a chance to run.
+ // Request contextualizers might not run before an abort, so guard optional request fields.
if (req.pagePath) {
incrementTags.push(`path:${req.pagePath}`)
}
diff --git a/src/frame/middleware/api.ts b/src/frame/middleware/api.ts
index a7c3f1acb7ac..4eef5c90a193 100644
--- a/src/frame/middleware/api.ts
+++ b/src/frame/middleware/api.ts
@@ -23,12 +23,8 @@ router.use('/anchor-redirect', anchorRedirect)
router.use('/pagelist', pageList)
router.use('/article', article)
-// The purpose of this is for convenience to everyone who runs this code
-// base locally but don't have an Elasticsearch server locally.
-// In production, this env var is always set but perhaps in a writer's
-// local laptop, they don't have an Elasticsearch. Neither a running local
-// server or the known credentials to a remote Elasticsearch. Whenever
-// that's the case, they can just HTTP proxy to the production server.
+// Local development proxies AI Search to docs.github.com when CSE_COPILOT_ENDPOINT
+// is unset, so writers do not need a local AI Search service.
if (process.env.CSE_COPILOT_ENDPOINT || process.env.NODE_ENV === 'test') {
router.use('/ai-search', aiSearch)
} else {
@@ -52,9 +48,8 @@ if (process.env.ELASTICSEARCH_URL) {
)
}
-// We need access to specific httpOnly cookies set on github.com from the client
-// The only way to access these on the client is to fetch them from the server
-// Limit this endpoint to 1req/min because a client should only call this route once
+// Browser JavaScript cannot read github.com httpOnly cookies.
+// The server endpoint returns the staff flag that client code needs.
router.get('/cookies', (req, res) => {
noCacheControl(res)
const cookies = {
diff --git a/src/frame/middleware/block-robots.ts b/src/frame/middleware/block-robots.ts
index 298575ec9f0c..c49e8f602f98 100644
--- a/src/frame/middleware/block-robots.ts
+++ b/src/frame/middleware/block-robots.ts
@@ -4,7 +4,7 @@ import { productMap } from '@/products/lib/all-products'
import { deprecated } from '@/versions/lib/enterprise-server-releases'
const pathRegExps: RegExp[] = [
- // Disallow indexing of WIP products
+ // WIP and hidden products stay out of search indexes.
...Object.values(productMap)
.filter((product) => product.wip || product.hidden)
.map((product) => [
@@ -12,7 +12,7 @@ const pathRegExps: RegExp[] = [
...product.versions!.map((version) => new RegExp(`^/.*?${version}/${product.id}`, 'i')),
]),
- // Disallow indexing of deprecated enterprise versions
+ // Deprecated enterprise versions stay out of search indexes.
...deprecated.map((version) => [
new RegExp(`^/.*?/enterprise-server@${version}/.*?`, 'i'),
new RegExp(`^/.*?/enterprise/${version}/.*?`, 'i'),
diff --git a/src/frame/middleware/cache-control.ts b/src/frame/middleware/cache-control.ts
index b53e5ca98364..c529f64f7918 100644
--- a/src/frame/middleware/cache-control.ts
+++ b/src/frame/middleware/cache-control.ts
@@ -19,9 +19,8 @@ const ONE_DAY = 24 * ONE_HOUR
const ONE_WEEK = 7 * ONE_DAY
const ONE_YEAR = 365 * ONE_DAY
-// Return a function you can pass a Response object to and it will set the `Cache-Control` header.
-// Max age is in seconds.
-// Max age should not be greater than 31536000, per .
+// maxAge is seconds. Keep it at or below 31536000.
+// https://www.ietf.org/rfc/rfc2616.txt
function cacheControlFactory(
maxAge: number = 0,
{
@@ -53,16 +52,14 @@ function cacheControlFactory(
}
}
-// The rest of this file is roughly in order from shortest max age to longest.
-
-// If you do not want caching.
export const noCacheControl = cacheControlFactory(0)
-// Short cache for 4xx errors.
+// 4xx errors get a short cache.
export const errorCacheControl = cacheControlFactory(ONE_MINUTE)
-// For default cache control, up to one week in cache but much shorter in browser.
-// Most responses are under the default cache control policy.
+// Default responses cache for 1 minute in browsers and 10 minutes in the CDN.
+// The CDN can serve stale responses for 1 week while revalidating or on errors.
+// Most responses use this policy.
const browserCacheControl = cacheControlFactory(ONE_MINUTE)
const defaultCDNCacheControl = cacheControlFactory(TEN_MINUTES, {
key: 'surrogate-control',
@@ -75,30 +72,29 @@ export function defaultCacheControl(res: Response): void {
}
export const searchCacheControl = defaultCacheControl
-// For requests where the response can vary between a HTML and Markdown response
-// using the accept header.
+// The Accept header can switch content responses between HTML and Markdown.
export function contentTypeCacheControl(res: Response): void {
defaultCacheControl(res)
res.append('vary', 'accept')
}
-// Vary on language when needed.
-// `x-user-language` is a custom request header derived from `req.cookie:user_language`.
-// `accept-language` is truncated to one of our available languages.
+// Vary by accept-language and x-user-language.
+// x-user-language comes from req.cookie:user_language.
+// Upstream code truncates accept-language to available languages.
// https://bit.ly/3u5UeRN
export function languageCacheControl(res: Response): void {
defaultCacheControl(res)
res.append('vary', 'accept-language, x-user-language')
}
-// Vary on both language and version for homepage redirects.
-// `x-user-version` is a custom request header derived from `req.cookie:user_version`.
+// Homepage redirects also vary by x-user-version.
+// x-user-version comes from req.cookie:user_version.
export function languageAndVersionCacheControl(res: Response): void {
defaultCacheControl(res)
res.append('vary', 'accept-language, x-user-language, x-user-version')
}
-// Long cache control for versioned assets: such as images, CSS, prebuilt JS.
+// Versioned images, CSS, and prebuilt JS use long browser and CDN caches.
const assetBrowserCacheControl = cacheControlFactory(TEN_MINUTES)
const assetCDNCacheControl = cacheControlFactory(ONE_WEEK, {
key: 'surrogate-control',
@@ -111,7 +107,7 @@ export function assetCacheControl(res: Response): void {
assetCDNCacheControl(res)
}
-// Long caching for archived pages and assets.
+// Archived pages and assets use long browser and CDN caches.
const archivedBrowserCacheControl = cacheControlFactory(TEN_MINUTES)
const archivedCDNCacheControl = cacheControlFactory(ONE_YEAR, {
key: 'surrogate-control',
diff --git a/src/frame/middleware/categories-for-support.ts b/src/frame/middleware/categories-for-support.ts
index ad8bae698a57..bf1bac8f945f 100644
--- a/src/frame/middleware/categories-for-support.ts
+++ b/src/frame/middleware/categories-for-support.ts
@@ -14,8 +14,7 @@ type Category = {
published_articles: Article[]
}
-// This middleware exposes a list of all categories and child articles at /categories.json.
-// GitHub Support uses this for internal ZenDesk search functionality.
+// /categories.json gives GitHub Support categories and child articles for Zendesk search.
export default async function categoriesForSupport(req: ExtendedRequest, res: Response) {
const englishSiteTree = req.context!.siteTree!.en
const allCategories: Category[] = []
@@ -26,9 +25,7 @@ export default async function categoriesForSupport(req: ExtendedRequest, res: Re
if (!productPage.childPages || !productPage.childPages.length) continue
await Promise.all(
productPage.childPages.map(async (categoryPage) => {
- // We can't get the rendered titles from middleware/render-tree-titles
- // here because that middleware only runs on the current version, and this
- // middleware processes all versions.
+ // Site-tree titles are raw, so render any that contain Liquid.
if (!req.context) return
const name = categoryPage.page.title.includes('{')
? await categoryPage.page.renderProp('title', req.context, renderOpts)
@@ -42,8 +39,7 @@ export default async function categoriesForSupport(req: ExtendedRequest, res: Re
)
}
- // Cache somewhat aggressively but note that it will be soft-purged
- // in every prod deployment.
+ // Use the default browser and CDN cache policy.
defaultCacheControl(res)
return res.json(allCategories)
@@ -67,7 +63,6 @@ async function findArticlesPerCategory(
if (!currentPage.childPages) return articlesArray
- // Run recursively to find any articles deeper in the tree.
await Promise.all(
currentPage.childPages.map(async (childPage) => {
await findArticlesPerCategory(childPage, articlesArray, context)
diff --git a/src/frame/middleware/context/breadcrumbs.ts b/src/frame/middleware/context/breadcrumbs.ts
index 9f5beba950dd..b6cbca12c224 100644
--- a/src/frame/middleware/context/breadcrumbs.ts
+++ b/src/frame/middleware/context/breadcrumbs.ts
@@ -10,7 +10,6 @@ export default function breadcrumbs(req: ExtendedRequest, res: Response, next: N
req.context.breadcrumbs = []
- // Return an empty array on the landing page.
if (req.context.page.documentType === 'homepage') {
return next()
}
@@ -22,21 +21,15 @@ export default function breadcrumbs(req: ExtendedRequest, res: Response, next: N
const earlyAccessExceptions = ['insights', 'enterprise-importer']
+// For Early Access pages, getBreadcrumbs omits /early-access and the product segment.
+// For example, /en/early-access/github/migrating starts at /migrating.
function getBreadcrumbs(req: ExtendedRequest, isEarlyAccess: boolean) {
if (!req.context || !req.context.currentPath || !req.context.currentProductTreeTitles)
throw new Error('request is not contextualized')
let cutoff = 0
- // When in Early access docs consider the "root" be much higher.
- // E.g. /en/early-access/github/migrating/understanding/about
- // we only want it start at /migrating/understanding/about
- // Essentially, we're skipping "/early-access" and its first
- // top-level like "/github"
if (isEarlyAccess) {
const split = req.context.currentPath!.split('/')
- // There are a few exceptions to this rule for the
- // /{version}/early-access//... URLs because they're a
- // bit different.
- // If there are more known exceptions, add them to the array above.
+ // insights and enterprise-importer Early Access URLs keep their product segment.
if (earlyAccessExceptions.some((product) => split.includes(product))) {
cutoff = 1
} else {
@@ -55,22 +48,7 @@ function getBreadcrumbs(req: ExtendedRequest, isEarlyAccess: boolean) {
return breadcrumbsResult
}
-// Return an array as if you'd traverse down a tree. Imagine a tree like
-//
-// (root /)
-// / \
-// (/foo) (/bar)
-// / \
-// (/foo/bar) (/foo/buzz)
-//
-// If the "currentPath" is `/foo/buzz` what you want to return is:
-//
-// [
-// {href: /, title: TITLE},
-// {href: /foo, title: TITLE}
-// {href: /foo/buzz, title: TITLE}
-// ]
-//
+// Example: /en/actions/learn-github-actions returns each matching ancestor and that page.
function traverseTreeTitles(currentPath: string | string[], tree: TitlesTree) {
const { href, title, shortTitle } = tree
const crumbs = [
@@ -85,17 +63,13 @@ function traverseTreeTitles(currentPath: string | string[], tree: TitlesTree) {
for (const child of tree.childPages) {
if (isParentOrEqualArray(child.href.split('/'), currentPathSplit)) {
crumbs.push(...traverseTreeTitles(currentPathSplit, child))
- // Only ever going down 1 of the children
break
}
}
return crumbs
}
-// Return true if an array is part of another array or equal.
-// Like `/foo/bar` is part of `/foo/bar/buzz`.
-// But also include `/foo/bar/buzz`.
-// Don't include `/foo/ba` if the final path is `/foo/baring`.
+// Compare split paths so /foo/ba does not match /foo/baring.
function isParentOrEqualArray(base: string[], final: string[]) {
return base.every((part, i) => part === final[i])
}
diff --git a/src/frame/middleware/context/context.ts b/src/frame/middleware/context/context.ts
index 7d0e0390b1da..b3dd70c75c50 100644
--- a/src/frame/middleware/context/context.ts
+++ b/src/frame/middleware/context/context.ts
@@ -19,19 +19,20 @@ import nonEnterpriseDefaultVersion from '@/versions/lib/non-enterprise-default-v
import { getDataByLanguage, getUIDataMerged } from '@/data-directory/lib/get-data'
import { updateLoggerContext } from '@/observability/logger/lib/logger-context'
-// This doesn't change just because the request changes, so compute it once.
+// Enterprise Server version keys do not depend on each request, so compute them once.
const enterpriseServerVersions = Object.keys(allVersions).filter((version) =>
version.startsWith('enterprise-server@'),
)
-// Supply all route handlers with a baseline `req.context` object
-// Note that additional middleware in middleware/index.ts adds to this context object
+// middleware/index.ts depends on contextualize setting baseline req.context.
+// For non-English pages, contextualize adds getEnglishPage for renderContentWithFallback.
+// It handles fallback-eligible Liquid, autotitle, and empty-title errors.
export default async function contextualize(
req: ExtendedRequest,
res: Response,
next: NextFunction,
) {
- // Ensure that we load some data only once on first request
+ // warmServer caches this data after the first request.
const { redirects, siteTree, pages: pageMap } = await warmServer([])
const context: Context = {}
@@ -40,17 +41,14 @@ export default async function contextualize(
req.context.process = { env: {} }
if (req.pagePath && req.pagePath.endsWith('.md')) {
- // req.pagePath is used later in the rendering pipeline to
- // locate the file in the tree so it cannot have .md
+ // The rendering pipeline resolves req.pagePath in the tree without the .md suffix.
req.pagePath = req.pagePath.replace(/\/index\.md$/, '').replace(/\.md$/, '')
req.context.markdownRequested = true
- // Track that markdown was requested via URL suffix, not Accept header.
- // This avoids adding a misleading Vary: accept cache header.
+ // markdownViaUrl avoids a misleading Vary: accept header for URL suffix requests.
req.context.markdownViaUrl = true
}
- // define each context property explicitly for code-search friendliness
- // e.g. searches for "req.context.page" will include results from this file
+ // Explicit req.context property assignments keep code search results discoverable.
req.context.currentLanguage = req.language
req.context.userLanguage = req.userLanguage
req.context.currentVersion = getVersionStringFromPath(req.pagePath) as string
@@ -62,8 +60,7 @@ export default async function contextualize(
req.context.allVersions = allVersions
req.context.currentPathWithoutLanguage = getPathWithoutLanguage(req.pagePath)
- // define property for writers to link to the current page in a different version
- // includes any type of rendered page not just "articles"
+ // currentArticle lets writers link any rendered page, not only articles, in another version.
req.context.currentArticle = getPathWithoutVersion(req.context.currentPathWithoutLanguage)
req.context.currentPath = req.pagePath
req.context.query = req.query
@@ -83,20 +80,15 @@ export default async function contextualize(
req.context.nonEnterpriseDefaultVersion = nonEnterpriseDefaultVersion
req.context.initialRestVersioningReleaseDate =
allVersions[nonEnterpriseDefaultVersion].apiVersions[0]
- // The default REST API version that requests use when no X-GitHub-Api-Version header is specified
- // This is the oldest supported version (last in the sorted descending array)
+ // apiVersions sorts newest first, so the last item is the default without X-GitHub-Api-Version.
const apiVersions = allVersions[nonEnterpriseDefaultVersion].apiVersions
req.context.defaultRestApiVersion = apiVersions[apiVersions.length - 1]
const restDate = new Date(req.context.initialRestVersioningReleaseDate)
req.context.initialRestVersioningReleaseDateLong = restDate.toUTCString().split(' 00:')[0]
- // Non-English pages need this so that `Page.render`, when it calls
- // `renderContentWithFallback`, can fall back to the English content when the
- // translation hits a fallback-eligible error (Liquid, autotitle, empty title).
if (req.language !== 'en') {
- // This is a function so the lookup only happens when a translated page
- // actually needs to fall back. Most requests never need it.
+ // getEnglishPage delays the lookup until a translated page needs fallback content.
req.context.getEnglishPage = (ctx) => {
if (!ctx.enPage) {
const { page } = ctx
diff --git a/src/frame/middleware/context/current-product-tree.ts b/src/frame/middleware/context/current-product-tree.ts
index 1a34c3015c83..c99b741c3b23 100644
--- a/src/frame/middleware/context/current-product-tree.ts
+++ b/src/frame/middleware/context/current-product-tree.ts
@@ -8,7 +8,6 @@ import findPageInSiteTree from '@/frame/lib/find-page-in-site-tree'
import removeFPTFromPath from '@/versions/lib/remove-fpt-from-path'
import { executeWithFallback } from '@/languages/lib/render-with-fallback'
-// This module adds currentProductTree to the context object for use in layouts.
export default async function currentProductTree(
req: ExtendedRequest,
res: Response,
@@ -18,7 +17,7 @@ export default async function currentProductTree(
if (!req.context.page) return next()
if (req.context.page.documentType === 'homepage') return next()
- // We need this so we can fall back to English if localized pages are out of sync.
+ // Keep the English tree available because localized pages can lag behind it.
if (!req.context.siteTree) throw new Error('siteTree is required')
if (!req.context.currentVersion) throw new Error('currentVersion is required')
req.context.currentEnglishTree = req.context.siteTree.en[req.context.currentVersion]
@@ -41,22 +40,17 @@ export default async function currentProductTree(
currentProductPath,
)
- // First make a slim tree of just the 'href', 'title', 'shortTitle'
- // 'documentType' and 'childPages' (which is recursive).
- // This gets used for subcategory and category pages.
+ // currentProductTreeTitles keeps href, title, shortTitle, documentType, and childPages.
req.context.currentProductTreeTitles = await getCurrentProductTreeTitles(
req.context.currentProductTree,
req.context,
)
- // Now make an even slimmer version that excludes all hidden pages.
- // This is used for sidebars.
+ // Sidebar data excludes hidden pages.
req.context.currentProductTreeTitlesExcludeHidden = excludeHidden(
req.context.currentProductTreeTitles,
)
- // Some pages, like hidden pages, don't have a tree. For example,
- // the search page. That one uses the same items as the homepage
- // for its sidebar.
+ // Hidden pages leave sidebarTree unset because excludeHidden returns null for the root.
if (req.context.currentProductTreeTitlesExcludeHidden) {
req.context.sidebarTree = sidebarTree(req.context.currentProductTreeTitlesExcludeHidden)
}
@@ -64,35 +58,18 @@ export default async function currentProductTree(
return next()
}
-// Return a nested object that contains the bits and pieces we need
-// for the tree which is used for sidebars and listing
async function getCurrentProductTreeTitles(input: Tree, context: Context): Promise {
const { page, href } = input
const childPages = await Promise.all(
(input.childPages || []).map((child) => getCurrentProductTreeTitles(child, context)),
)
- // If the current page is a translation we're going to need the English
- // equivalent for multiple things later in this function.
+ // Translated pages need their English page for fallback rendering and short-title comparison.
const enPage =
page.languageCode !== 'en' ? context.pages![href.replace(`/${page.languageCode}`, '/en')] : null
- let rawShortTitle = page.rawShortTitle // might change our minds about this
- // A lot of translations have a short title that is identical to the
- // English equivalent. E.g.
- //
- // content/foo.md:
- //
- // title: Something Something Bla
- // shortTitle: Something
- //
- // translations/docs-internal.se-sv/content/foo.md:
- //
- // title: Nånting Nånting Blä
- // shortTitle: Something
- //
- // I.e. the translations `shortTitle` hasn't been translated.
- // If this is the case, use the long title instead.
+ let rawShortTitle = page.rawShortTitle
+ // Swaps in rawTitle when shortTitle matches English, but the render below reads page.rawShortTitle.
if (page.languageCode !== 'en' && page.rawShortTitle) {
if (page.rawShortTitle === enPage!.shortTitle) {
rawShortTitle = page.rawTitle
@@ -112,8 +89,7 @@ async function getCurrentProductTreeTitles(input: Tree, context: Context): Promi
)
}
- // If the short title was present but "useless" (same as the title),
- // force it to be an empty string to not waste space.
+ // Empty duplicate short titles to avoid wasting sidebar space.
const shortTitle =
renderedShortTitle && (renderedShortTitle || '') !== renderedFullTitle ? renderedShortTitle : ''
@@ -148,12 +124,10 @@ function excludeHidden(tree: TitlesTree) {
function sidebarTree(tree: TitlesTree) {
const { href, title, shortTitle, childPages, sidebarLink } = tree
- // Filter out cross-product children from the sidebar
+ // Sidebars show only children from the current product.
const filteredChildPages = childPages.filter((child) => !child.crossProductChild)
- // Filter out children that are descendants of another sibling.
- // When a page lists both a subdirectory and individual articles from it,
- // the articles should only appear nested under the subdirectory in the sidebar.
+ // If siblings include a subdirectory and its articles, nest the articles under the subdirectory.
const siblingHrefs = filteredChildPages.map((c) => c.href)
const dedupedChildPages = filteredChildPages.filter(
(child) => !siblingHrefs.some((sh) => sh !== child.href && child.href.startsWith(`${sh}/`)),
diff --git a/src/frame/middleware/context/generic-toc.ts b/src/frame/middleware/context/generic-toc.ts
index 93a57bf99f91..67012fe6c363 100644
--- a/src/frame/middleware/context/generic-toc.ts
+++ b/src/frame/middleware/context/generic-toc.ts
@@ -12,9 +12,7 @@ function isNewLandingPage(currentLayoutName: string): boolean {
)
}
-// This module adds either flatTocItems or nestedTocItems to the context object for
-// product, category, and subcategory TOCs that don't have other layouts specified.
-// They are rendered by includes/generic-toc-flat.html or includes/generic-toc-nested.html.
+// genericToc assigns genericTocFlat or genericTocNested for React landing contexts.
export default async function genericToc(req: ExtendedRequest, res: Response, next: NextFunction) {
if (!req.context) throw new Error('request not contextualized')
if (!req.context.page) return next()
@@ -23,7 +21,7 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
!isNewLandingPage(req.context.currentLayoutName || '')
)
return next()
- // This middleware can only run on product, category, and subcategories.
+ // TOC layouts skip homepages, articles, and search.
if (
req.context.page.documentType === 'homepage' ||
req.context.page.documentType === 'article' ||
@@ -39,8 +37,7 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
subcategory: 'flat',
}
- // Frontmatter can optionally be set on an Early Access product to show hidden child items.
- // If so, this is a special case where we want to override the flat tocType and use a nested type.
+ // earlyAccessToc frontmatter exposes hidden child items by switching products to nested TOCs.
const earlyAccessToc = req.context.page.earlyAccessToc
if (!req.context.currentProductTree) throw new Error('currentProductTree not in context')
@@ -53,10 +50,7 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
req.pagePath,
)
- // The intent is that a category whose children have no children of their own
- // should render like a subcategory. It doesn't work: `child.children` is `[]`
- // for leaf pages and `[]` is truthy, so `hasGrandchildren` is true for any
- // category with children at all. This probably wants `child.children?.length`.
+ // fauxSubcategory is meant to flatten categories without grandchildren, but [] is truthy.
let fauxSubcategory = false
if (req.context.page.documentType === 'category' && req.context.page.autogenerated !== 'rest') {
const hasGrandchildren = (treePage.childPages || []).some((child) => child.children)
@@ -69,10 +63,7 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
? 'flat'
: tocTypes[req.context.page.documentType]
- // By default, only include hidden child items on a TOC page if it's an Early Access category or
- // subcategory page, not a product or 'articles' fake category page (e.g., /early-access/github/articles).
- // This is because we don't want entire EA product TOCs to be publicly browseable, but anything at the category
- // or below level is fair game because that content is scoped to specific features.
+ // By default, Early Access category and subcategory TOCs expose hidden children except /articles.
const isCategoryOrSubcategory =
req.context.page.documentType === 'category' || req.context.page.documentType === 'subcategory'
if (!req.context.currentPath) throw new Error('currentPath not in context')
@@ -85,7 +76,6 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
let isRecursive
let renderIntros
- // Get an array of child links with intros and add it to the context object.
if (currentTocType === 'flat' && !isOneOffProductToc) {
isRecursive = false
renderIntros = true
@@ -97,7 +87,6 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
})
}
- // Get an array of child subcategories and their child articles and add it to the context object.
if (currentTocType === 'nested' || isOneOffProductToc) {
isRecursive = !isOneOffProductToc
renderIntros = false
@@ -119,8 +108,9 @@ type Options = {
textOnly: boolean
}
+// rawIntro can contain Markdown without Liquid, so renderProp still needs to process it.
+// Generic TOC components keep intro HTML unless a landing-page layout needs text only.
async function getTocItems(node: Tree, context: Context, opts: Options): Promise {
- // Cleaner than trying to be too terse inside the `.filter()` inline callback.
function filterHidden(child: Tree): boolean {
return opts.includeHidden || !child.page.hidden
}
@@ -138,11 +128,6 @@ async function getTocItems(node: Tree, context: Context, opts: Options): Promise
if (opts.renderIntros) {
intro = ''
if (page.rawIntro) {
- // The intro can contain Markdown even though it might not
- // contain any Liquid.
- // Use textOnly for new landing pages to strip HTML tags.
- // For other pages, we intend to display the intro in a table of contents
- // component with the HTML (dangerouslySetInnerHTML).
intro = await page.renderProp(
'rawIntro',
context,
diff --git a/src/frame/middleware/context/glossaries.ts b/src/frame/middleware/context/glossaries.ts
index 8d49f6a815e2..8b7c81cef50c 100644
--- a/src/frame/middleware/context/glossaries.ts
+++ b/src/frame/middleware/context/glossaries.ts
@@ -12,18 +12,11 @@ export default async function glossaries(req: ExtendedRequest, res: Response, ne
if (!req.context) throw new Error('request is not contextualized')
- // If the current version (which is found as part of the URL), does not
- // correspond to a supported version, the Liquid rendering will fail
- // (if there's uses of `ifversion` in any the Liquid).
- // So we'll skip this contextualizer and let the 404 error take over later.
+ // Skip unsupported versions so ifversion Liquid errors do not replace the later 404.
if (!req.context.currentVersionObj) return next()
- // When the current language is *not* English, we'll need to get the English
- // glossary based on the term. We'll use this to render the translated
- // glossaries. For example, if the Korean translation has a corruption
- // in its description we need to know the English equivalent.
+ // Translated glossaries need English descriptions to repair corrupted Liquid before rendering.
const enGlossaryMap = new Map()
- // But we don't need to bother if the current language is English.
if (req.context.currentLanguage !== 'en') {
const enGlossariesRaw: Glossary[] = getDataByLanguage('glossaries.external', 'en') as Glossary[]
@@ -32,11 +25,7 @@ export default async function glossaries(req: ExtendedRequest, res: Response, ne
}
}
- // The glossaries Yaml file contains descriptions that might contain
- // Liquid. They need to be rendered out.
- // The github-glossary.md file uses Liquid to generate the Markdown.
- // It uses Liquid to say `{{ glossary.description }}` but once that's
- // injected there it needs to have its own possible Liquid rendered out.
+ // github-glossary.md injects glossary descriptions before their Liquid renders.
const glossariesRaw: Glossary[] = getDataByLanguage(
'glossaries.external',
req.context.currentLanguage!,
@@ -48,13 +37,7 @@ export default async function glossaries(req: ExtendedRequest, res: Response, ne
if (req.context!.currentLanguage !== 'en') {
description = correctTranslatedContentStrings(
description,
- // The function needs the English equivalent of the translated
- // Markdown. It's to make possible corrections to the
- // translation's Liquid which might have lost important
- // linebreaks.
- // But because the terms themselves are often translated,
- // in this mapping we often don't have an English equivalent.
- // So that's why we fall back on the empty string.
+ // English Markdown repairs Liquid line breaks; some translated terms lack matches.
enGlossaryMap.get(glossary.term) || '',
{ code: req.context!.currentLanguage },
)
@@ -64,17 +47,13 @@ export default async function glossaries(req: ExtendedRequest, res: Response, ne
() => liquid.parseAndRender(description, req.context),
(enContext: Context) => {
const { term } = glossary
- // It *could* be that the translation is referring to a term
- // that no longer exists in the English glossary. In that case,
- // simply skip this term.
+ // Skip translated terms missing from the English glossary.
if (!enGlossaryMap.has(term)) return
const enDescription = enGlossaryMap.get(term)
return liquid.parseAndRender(enDescription, enContext)
},
)
- // It's important to use `Object.assign` here to avoid mutating the
- // original object because from `getDataByLanguage`, reads from an
- // in-memory cache so if we mutated it, it would be mutated for all.
+ // Object.assign preserves the getDataByLanguage cache object shared across requests.
return Object.assign({}, glossary, { description })
}),
)
diff --git a/src/frame/middleware/context/layout.ts b/src/frame/middleware/context/layout.ts
index 447955cc8917..45f3a5342c84 100644
--- a/src/frame/middleware/context/layout.ts
+++ b/src/frame/middleware/context/layout.ts
@@ -9,7 +9,7 @@ export default function layoutContext(req: ExtendedRequest, res: Response, next:
let layoutName = 'default'
if (req.context.page.layout) {
if (typeof req.context.page.layout === 'boolean') {
- // A `layout: false` value means use no layout.
+ // Only layout: true reaches here and clears the layout name. layout: false gets the default.
layoutName = ''
} else if (typeof req.context.page.layout === 'string') {
layoutName = req.context.page.layout
diff --git a/src/frame/middleware/context/product-groups.ts b/src/frame/middleware/context/product-groups.ts
index 6a9427277394..b875c711d5b4 100644
--- a/src/frame/middleware/context/product-groups.ts
+++ b/src/frame/middleware/context/product-groups.ts
@@ -8,18 +8,20 @@ import { allVersionKeys } from '@/versions/lib/all-versions'
const isHomepage = (path: string) => {
const split = path.split('/')
- // E.g. `/foo` but not `foo/bar` or `foo/`
+ // Matches /en but not en/foo or /en/.
if (split.length === 2 && split[1] && !split[0]) {
return languageKeys.includes(split[1])
}
- // E.g. `/foo/possiblyproductname` but not `foo/possiblyproductname` or
- // `/foo/something/`
+ // Matches /en/free-pro-team@latest but not en/free-pro-team@latest or /en/actions/.
if (split.length === 3 && !split[0] && split[2]) {
return allVersionKeys.includes(split[2])
}
return false
}
+// handleNextDataPath maps Next data URLs, such as /_next/data/development/en/actions.json,
+// to normal page paths, so productGroups reads req.pagePath.
+// It requires a valid currentVersionObj because ifversion Liquid in getProductGroups throws otherwise.
export default async function productGroups(
req: ExtendedRequest,
res: Response,
@@ -28,18 +30,6 @@ export default async function productGroups(
if (!req.context) throw new Error('request is not contextualized')
if (!req.pagePath) throw new Error('pagePath is not set on request')
if (!req.language) throw new Error('language is not set on request')
- // It's important to use `req.pagePath` instead of `req.path` because
- // the request could be the client-side routing from Next where the URL
- // might be something like `/_next/data/foo/bar.json` which is translated,
- // in another middleware, to what it would equate to if it wasn't
- // client-side routing.
- // Before executing getProductGroups, which might need to do some
- // Liquid parsing & executing, we want to make sure the request
- // does have a valid version.
- // The `currentVersion` is taken from the `req.path` but
- // `currentVersionObj` is looking up `currentVersion` with all
- // known versions. Because if it's not valid, any possible
- // use of `{% ifversion ... %}` in Liquid, will throw an error.
if (isHomepage(req.pagePath) && req.context.currentVersionObj) {
const { pages } = await warmServer([])
req.context.productGroups = await getProductGroups(pages, req.language, req.context)
diff --git a/src/frame/middleware/context/render-product-name.ts b/src/frame/middleware/context/render-product-name.ts
index 151afab5cc68..2ca7b2f85c50 100644
--- a/src/frame/middleware/context/render-product-name.ts
+++ b/src/frame/middleware/context/render-product-name.ts
@@ -12,13 +12,12 @@ export default async function renderProductName(
const { productMap, currentProduct } = req.context
if (!productMap) throw new Error('request is not contextualized')
- // `currentProduct` might be an empty string, which is a valid value.
+ // Empty currentProduct is valid.
if (currentProduct === undefined) throw new Error('currentProduct is not contextualized')
const productObject = productMap[currentProduct]
if (!productObject) {
- // If the "currentProduct" isn't recognized, there's no point trying
- // to render its name. Skip this middleware.
+ // Skip unrecognized currentProduct values because renderContent needs a product object.
return next()
}
req.context.currentProductName = await renderContent(productObject.name, req.context, {
diff --git a/src/frame/middleware/cookie-parser.ts b/src/frame/middleware/cookie-parser.ts
index ffe82e348ba0..f9bc1e2e43f2 100644
--- a/src/frame/middleware/cookie-parser.ts
+++ b/src/frame/middleware/cookie-parser.ts
@@ -5,8 +5,7 @@ import { cookieSettings } from '@/frame/lib/cookie-settings'
export default cookieParser(
process.env.COOKIE_SECRET,
- // `cookie-settings.ts` declares these as `CookieSerializeOptions` because
- // that is the right type for the places that set cookies. cookie-parser
- // wants `CookieParseOptions`, so bridge the two here.
+ // cookie-settings.ts exports CookieSerializeOptions for cookie writers.
+ // cookie-parser expects CookieParseOptions, so bridge the two here.
cookieSettings as CookieParseOptions,
)
diff --git a/src/frame/middleware/fast-head.ts b/src/frame/middleware/fast-head.ts
index 2930aeda248f..cd6475d0df32 100644
--- a/src/frame/middleware/fast-head.ts
+++ b/src/frame/middleware/fast-head.ts
@@ -8,8 +8,7 @@ export default function fastHead(req: ExtendedRequest, res: Response, next: Next
const { context } = req
const { page } = context
if (page) {
- // Since the *presence* is not affected by the request, we can cache
- // this and allow the CDN to hold on to it.
+ // Cache by URL because request headers do not change this empty HEAD response.
defaultCacheControl(res)
res.status(200).send('')
diff --git a/src/frame/middleware/fastly-cache-test.ts b/src/frame/middleware/fastly-cache-test.ts
index 4970fc9fa9be..b1908a3dbf82 100644
--- a/src/frame/middleware/fastly-cache-test.ts
+++ b/src/frame/middleware/fastly-cache-test.ts
@@ -1,19 +1,13 @@
-//
-// This middleware function is intended to be used for testing caching behavior with Fastly.
-// It will intercept ALL URLs that are routed to it and respond with a simple HTML body
-// containing a timestamp.
-// The logic will detect certain values in the path and set the HTTP status and/or the
-// Surrogate-Control header value.
-//
-// NOTE: This middleware is intended to be removed once testing is complete!
-//
+// Tests Fastly caching by returning timestamped HTML for any routed URL.
+// Path tokens set the HTTP status and cache directives.
+// X-CacheTest-CCMode chooses Surrogate-Control, Cache-Control, or both.
import express from 'express'
import crypto from 'crypto'
const router = express.Router()
router.get('/*path', function (req, res) {
- // If X-CacheTest-Error is set, simulate the site being down (regardless of URL)
+ // X-CacheTest-Error simulates a site outage for any URL.
if (req.get('X-CacheTest-Error')) {
res.status(parseInt(req.get('X-CacheTest-Error') as string)).end()
return
diff --git a/src/frame/middleware/favicons.ts b/src/frame/middleware/favicons.ts
index 44993db15454..de496bdb6245 100644
--- a/src/frame/middleware/favicons.ts
+++ b/src/frame/middleware/favicons.ts
@@ -1,8 +1,5 @@
-// We actually don't rely and use /favicon.ico but it's nevertheless a
-// very common request. Same with /apple-touch-icon.png.
-// Because we store our images, including those not for the Markdown text,
-// in the `assets/images/site` directory, we will use a custom
-// solution to serve this directly.
+// Browsers request /favicon.ico and Apple touch icons even though pages do not link them.
+// Serve these root icon URLs directly from assets/images/site.
import fs from 'fs'
import type { Response, NextFunction } from 'express'
@@ -36,10 +33,7 @@ const MAP: {
},
}
-// It's the same image but it's fine. By default, when Safari tries to
-// to figure out which apple touch icons are available it will
-// try to load this by default. For example, if you in desktop Safari
-// click share icon, it will load this to serve as a preview icon.
+// Safari probes precomposed Apple touch icon names for desktop share previews.
MAP['/apple-touch-icon-precomposed.png'] = MAP['/apple-touch-icon.png']
MAP['/apple-touch-icon-120x120-precomposed.png'] = MAP['/apple-touch-icon-120x120.png']
MAP['/apple-touch-icon-152x152-precomposed.png'] = MAP['/apple-touch-icon-152x152.png']
@@ -51,9 +45,7 @@ function getBuffer(filePath: string) {
}
return () => {
if (!buffer) {
- // Yes, sync and a bit slow, but the headers we send will
- // make sure these requests are rare because the payload
- // will be sticky in the CDN and stickly in the browser too.
+ // Sync reads are rare because assetCacheControl keeps icons in the CDN and browser cache.
buffer = fs.readFileSync(filePath)
}
return buffer
@@ -63,11 +55,10 @@ function getBuffer(filePath: string) {
export default function favicons(req: ExtendedRequest, res: Response, next: NextFunction) {
if (!MAP[req.path]) return next()
- // This makes sure the CDN caching survives each production deployment.
+ // The manual surrogate key keeps CDN caching through production deploys.
setFastlySurrogateKey(res, SURROGATE_ENUMS.MANUAL)
- // Manually settings a Cache-Control because no other middleware
- // will get a chance to do this later since we terminate here.
+ // Set asset caching here because this middleware sends the response.
assetCacheControl(res)
const { contentType, buffer } = MAP[req.path]
diff --git a/src/frame/middleware/find-page.ts b/src/frame/middleware/find-page.ts
index 7f606fc4abb4..12ea98233c80 100644
--- a/src/frame/middleware/find-page.ts
+++ b/src/frame/middleware/find-page.ts
@@ -15,18 +15,19 @@ interface FindPageOptions {
const englishPrefixRegex = /^\/en(\/|$)/
const CONTENT_ROOT = path.join(ROOT, 'content')
+// Development rereads of index pages keep startup versions and permalinks.
+// Tree construction mutates category pages from child versions, but rereads use only file data.
export default async function findPage(
req: ExtendedRequest,
res: Response,
next: NextFunction,
- // Express won't execute these but it makes it easier to unit test
- // the middleware.
+ // Express ignores these options, but tests can pass them directly.
{
isDev = process.env.NODE_ENV === 'development',
contentRoot = CONTENT_ROOT,
}: FindPageOptions = {},
): Promise {
- // Filter out things like `/will/redirect` or `/_next/data/...`
+ // Only language-prefixed content paths can map to pages; /will/redirect continues.
if (!req.pagePath || !languagePrefixPathRegex.test(req.pagePath)) {
return next()
}
@@ -37,11 +38,6 @@ export default async function findPage(
let page = req.context.pages[req.pagePath] as Page | undefined
if (page && isDev && englishPrefixRegex.test(req.pagePath)) {
- // The .applicableVersions and .permalinks properties are computed
- // when the page is read in from disk. But when the initial tree
- // was created at startup, the pages in the tree were mutated
- // based on their context. For example, a category page's versions
- // is based on looping through all its children's versions.
const reuseOldVersions = page.relativePath.endsWith('index.md')
const oldApplicableVersions = page.applicableVersions
const oldPermalinks = page.permalinks
@@ -59,9 +55,7 @@ export default async function findPage(
page.permalinks = oldPermalinks
}
- // This can happen if the page we just re-read has changed which
- // versions it's available in (the `versions` frontmatter) meaning
- // it might no longer be available on the current URL.
+ // A reread page can drop the requested version from applicableVersions.
if (
req.context?.currentVersion &&
!page.applicableVersions.includes(req.context.currentVersion)
@@ -80,9 +74,7 @@ export default async function findPage(
req.context.page = page
;(req.context.page as Page & { version: string }).version = req.context.currentVersion || ''
- // We can't depend on `page.hidden` because the dedicated search
- // results page is a hidden page but it needs to offer all possible
- // languages.
+ // page.hidden also hides search, which needs every language; restrict only early-access pages.
if (page.relativePath.startsWith('early-access') && req.context?.languages?.en) {
req.context.languages = {
en: req.context.languages.en,
@@ -93,6 +85,7 @@ export default async function findPage(
return next()
}
+// rereadByPath handles only English content because translations load at build time.
async function rereadByPath(
uri: string,
contentRoot: string,
@@ -103,18 +96,12 @@ async function rereadByPath(
const languageCode = match[1]
const withoutLanguage = uri.replace(languagePrefixPathRegex, '/')
const withoutVersion = withoutLanguage.replace(`/${currentVersion}`, '')
- // Note: We don't support loading translations at runtime. All translations
- // are loaded at build time. This function only handles English content reloading
- // during development.
const possible = path.join(contentRoot, withoutVersion)
const filePath = existsSync(possible) ? path.join(possible, 'index.md') : `${possible}.md`
const relativePath = path.relative(contentRoot, filePath)
const basePath = contentRoot
- // Remember, the Page.init() can return a Promise that resolves to falsy
- // if it can't read the file in from disk. E.g. a request for /en/non/existent.
- // In other words, it's fine if it can't be read from disk. It'll get
- // handled and turned into a nice 404 message.
+ // When a reread fails, the caller keeps the already-found page.
const page = await Page.init({
basePath,
relativePath,
diff --git a/src/frame/middleware/handle-next-data-path.ts b/src/frame/middleware/handle-next-data-path.ts
index 882720748ce0..78eb3e6748b9 100644
--- a/src/frame/middleware/handle-next-data-path.ts
+++ b/src/frame/middleware/handle-next-data-path.ts
@@ -5,16 +5,15 @@ import type { ExtendedRequest } from '@/types'
const STATSD_KEY = 'middleware.handle_next_data_path'
+// Client route transitions request _next/data JSON paths; map them back to page paths.
+// Example: /_next/data/development/en/actions/foo.json becomes
+// /en/actions/foo.
export default function handleNextDataPath(
req: ExtendedRequest,
res: Response,
next: NextFunction,
) {
if (req.path.startsWith('/_next/data/') && req.path.endsWith('.json')) {
- // translate a nextjs data request to a page path that the server can use on context
- // this is triggered via client-side route transitions
- // example path:
- // /_next/data/development/en/free-pro-team%40latest/github/setting-up-and-managing-your-github-user-account.json
let decodedPath = ''
try {
decodedPath = decodeURIComponent(req.path)
@@ -26,7 +25,7 @@ export default function handleNextDataPath(
}
const parts = decodedPath.split('/').slice(4)
- // free-pro-team@latest should not be included in the page path
+ // Drop free-pro-team@latest because page paths omit that default version.
if (parts[1] === 'free-pro-team@latest') {
parts.splice(1, 1)
}
diff --git a/src/frame/middleware/healthcheck.ts b/src/frame/middleware/healthcheck.ts
index 68e3089b17d5..514e1688ee53 100644
--- a/src/frame/middleware/healthcheck.ts
+++ b/src/frame/middleware/healthcheck.ts
@@ -4,11 +4,8 @@ import statsd from '@/observability/lib/statsd'
const router = express.Router()
-// Returns the healthiness of the service.
-// Moda may use this to decide whether this instance stays in the pool.
-// Today it checks nothing and always returns 200. If we ever needed to drain
-// an instance, for example on a failing dependency, this is where a 500
-// would go.
+// Moda may use this endpoint to decide whether an instance stays in the pool.
+// It always returns 200 and sends memory gauges to StatsD, without testing service health.
router.get('/', function healthcheck(req, res) {
noCacheControl(res)
diff --git a/src/frame/middleware/helmet.ts b/src/frame/middleware/helmet.ts
index ddbd4b90e8a1..7814bcde5975 100644
--- a/src/frame/middleware/helmet.ts
+++ b/src/frame/middleware/helmet.ts
@@ -9,11 +9,8 @@ import { colorModeScript } from '@/color-schemes/lib/color-mode-script'
const isDev = process.env.NODE_ENV === 'development'
-// The pre-paint theme script in `_document.tsx` is inlined, so it needs an
-// explicit CSP `script-src` allowance. We hash the exact script string rather
-// than using a nonce, because a nonce would have to vary per response and would
-// break the shared CDN cache. The script is identical for every request, so its
-// hash is stable and the HTML stays cacheable.
+// The pre-paint theme script from _document.tsx is inline, so CSP needs a script-src hash.
+// A nonce would vary per response and break shared CDN caching.
const colorModeScriptHash = `'sha256-${createHash('sha256').update(colorModeScript).digest('base64')}'`
const GITHUB_DOMAINS = [
"'self'",
@@ -29,22 +26,19 @@ const DEFAULT_OPTIONS = {
referrerPolicy: {
policy: 'no-referrer-when-downgrade' as const,
},
- // This module defines a Content Security Policy (CSP) to disallow
- // inline scripts and content from untrusted sources.
+ // The default CSP blocks untrusted origins and limits inline scripts to approved hashes.
contentSecurityPolicy: {
directives: {
defaultSrc: ["'none'"],
prefetchSrc: ["'self'"],
- // When doing local dev, especially in Safari, you need to add `ws:`
- // which NextJS uses for the hot module reloading.
+ // Safari local development needs ws: for Next.js hot module reloading.
connectSrc: ["'self'", 'https://collector.githubapp.com', isDev && 'ws:'].filter(
Boolean,
) as string[],
fontSrc: ["'self'", 'data:'],
imgSrc: [...GITHUB_DOMAINS, 'data:', 'placehold.it'],
objectSrc: ["'self'"],
- // For use during development only!
- // `unsafe-eval` allows us to use a performant webpack devtool setting (eval)
+ // Development webpack eval devtool needs unsafe-eval.
// https://webpack.js.org/configuration/devtool/#devtool
scriptSrc: [
...GITHUB_DOMAINS,
@@ -57,16 +51,17 @@ const DEFAULT_OPTIONS = {
frameSrc: [
...GITHUB_DOMAINS,
isDev && 'http://localhost:3000',
- // ArticleContext.tsx sets this URL too. We don't import a shared
- // constant because the env var may not be set yet at import time.
+ // src/frame/components/context/ArticleContext.tsx sets this URL too.
+ // A shared constant could capture SUPPORT_PORTAL_URL before it is set.
process.env.NODE_ENV === 'production'
? 'https://support.github.com'
- : // Assume that a developer is not testing the VA iframe locally if this env var is not set
+ : // Missing SUPPORT_PORTAL_URL means local development is not testing the VA iframe.
process.env.SUPPORT_PORTAL_URL || '',
].filter(Boolean) as string[],
frameAncestors: isDev ? ['*'] : [...GITHUB_DOMAINS],
styleSrc: [...GITHUB_DOMAINS, "'self'", "'unsafe-inline'", 'data:'],
- childSrc: ["'self'"], // exception for search in deprecated GHE versions
+ // Deprecated GitHub Enterprise search still needs child-src.
+ childSrc: ["'self'"],
manifestSrc: ["'self'"],
upgradeInsecureRequests: isDev ? null : [],
},
@@ -100,23 +95,21 @@ const staticDeprecatedHelmet = helmet(STATIC_DEPRECATED_OPTIONS)
const developerDeprecatedHelmet = helmet(DEVELOPER_DEPRECATED_OPTIONS)
export default function helmetMiddleware(req: Request, res: Response, next: NextFunction) {
- // Enable CORS
if (['GET', 'OPTIONS'].includes(req.method)) {
res.set('access-control-allow-origin', '*')
}
- // Determine version for exceptions
const { requestedVersion } = isArchivedVersion(req)
- // Check if this is a legacy developer.github.com path
const isDeveloper = req.path
.replace(languagePrefixPathRegex, '/')
.startsWith(`/enterprise/${requestedVersion}/developer`)
if (versionSatisfiesRange(requestedVersion, '<=2.18') && isDeveloper) {
+ // Deprecated developer.github.com paths need Google font and inline script exceptions.
return developerDeprecatedHelmet(req, res, next)
}
- // Exception for deprecated Enterprise docs (Node.js era)
+ // Node.js-era deprecated Enterprise docs need relaxed CSP directives.
if (
versionSatisfiesRange(requestedVersion, '<=2.19') &&
versionSatisfiesRange(requestedVersion, '>2.12')
@@ -124,7 +117,7 @@ export default function helmetMiddleware(req: Request, res: Response, next: Next
return nodeDeprecatedHelmet(req, res, next)
}
- // Exception for search in deprecated Enterprise docs <=2.12 (static site era)
+ // Static-site-era Enterprise search needs inline scripts.
if (versionSatisfiesRange(requestedVersion, '<=2.12')) {
return staticDeprecatedHelmet(req, res, next)
}
diff --git a/src/frame/middleware/index.ts b/src/frame/middleware/index.ts
index d4070063dd82..41aa501ce6a8 100644
--- a/src/frame/middleware/index.ts
+++ b/src/frame/middleware/index.ts
@@ -69,7 +69,7 @@ import urlDecode from './url-decode'
const ENABLE_FASTLY_TESTING = JSON.parse(process.env.ENABLE_FASTLY_TESTING || 'false')
-// Catch unhandled promise rejections and passing them to Express's error handler
+// asyncMiddleware passes unhandled promise rejections to Express's error handler.
// https://medium.com/@Abazhenov/using-async-await-in-express-with-node-8-b8af872c0016
const asyncMiddleware =
(
@@ -83,63 +83,38 @@ const asyncMiddleware =
}
}
+// trust proxy makes req.ip read the left-most X-Forwarded-For value for rate limits and logs.
+// https://expressjs.com/en/guide/behind-proxies.html
export default function index(app: Express) {
app.use(abort)
- // Don't use the proxy's IP, use the requester's for rate limiting or
- // logging.
- // See https://expressjs.com/en/guide/behind-proxies.html
- // Essentially, setting this means it believe that the IP is the
- // first of the `X-Forwarded-For` header values.
- // If it was 0 (or false), the value would be that
- // of `req.socket.remoteAddress`.
- // Now, the `req.ip` becomes the first entry from x-forwarded-for
- // and falls back on `req.socket.remoteAddress` in all other cases.
- // Their documentation says:
- //
- // If true, the client's IP address is understood as the
- // left-most entry in the X-Forwarded-For header.
- //
app.set('trust proxy', true)
- // *** Logging ***
- app.use(initLoggerContext) // Context for both inline logs (e.g. logger.info) and automatic logs
- app.use(getAutomaticRequestLogger()) // Automatic logging for all requests e.g. "GET /path 200"
- app.use(expressMetrics) // StatsD metrics for response time and status codes
+ app.use(initLoggerContext)
+ app.use(getAutomaticRequestLogger())
+ app.use(expressMetrics)
- // Put this early to make it as fast as possible because it's used
- // to check the health of each cluster.
+ // Keep healthcheck early so cluster probes skip slower middleware.
app.use('/healthcheck', healthcheck)
- // Must appear before static assets and all other requests
- // otherwise we won't be able to benefit from that functionality
- // for static assets as well.
+ // Default surrogate keys must run before static assets, so static responses can inherit them.
app.use(setDefaultFastlySurrogateKey)
- // Attaches res.safeRedirect() to every response. Must appear before
- // any middleware that redirects.
+ // safeRedirect must run before middleware that redirects.
app.use(safeRedirect)
- // archivedEnterpriseVersionsAssets must come before static/assets
+ // archivedEnterpriseVersionsAssets must run before static asset middleware.
app.use(asyncMiddleware(archivedEnterpriseVersionsAssets))
app.use(favicons)
- // Any static URL that contains some sort of checksum that makes it
- // unique gets the "manual" surrogate key. If it's checksummed,
- // it's bound to change when it needs to change. Otherwise,
- // we want to make sure it doesn't need to be purged just because
- // there's a production deploy.
- // Note, for `/assets/cb-*...` requests,
- // this needs to come before `assetPreprocessing` because
- // the `assetPreprocessing` middleware will rewrite `req.url` if
- // it applies.
+ // Checksummed assets keep manual keys; assetPreprocessing later rewrites /assets/cb-* URLs.
app.use(setStaticAssetCaching)
- // Must come before any other middleware for assets
+ // archivedAssetRedirects must run before other asset middleware.
app.use(archivedAssetRedirects)
- // This must come before the express.static('assets') middleware.
+ // assetPreprocessing must run before express.static assets.
app.use(assetPreprocessing)
app.use(
@@ -147,11 +122,10 @@ export default function index(app: Express) {
express.static('assets', {
index: false,
etag: false,
- // Can be aggressive because images inside the content get unique
- // URLs with a cache busting prefix.
+ // Content image URLs have cache-busting prefixes, so assets can cache aggressively.
maxAge: '7 days',
immutable: process.env.NODE_ENV !== 'development',
- // The next middleware will try its luck and send the 404 if must.
+ // Let later middleware send the asset 404.
fallthrough: true,
}),
)
@@ -161,15 +135,13 @@ export default function index(app: Express) {
express.static('src/graphql/data', {
index: false,
etag: false,
- maxAge: '7 days', // A bit longer since releases are more sparse
- // See note about the use of 'fallthrough'
+ maxAge: '7 days', // Sparse releases tolerate longer caching.
+ // Missing release assets 404 here.
fallthrough: false,
}),
)
- // In development, let NextJS on-the-fly serve the static assets.
- // But in production, don't let NextJS handle any static assets
- // because they are costly to generate (the 404 HTML page).
+ // In production, skip Next static handling because generated 404 HTML is expensive.
if (process.env.NODE_ENV !== 'development') {
const assetDir = path.join('.next', 'static')
if (!fs.existsSync(assetDir))
@@ -182,60 +154,52 @@ export default function index(app: Express) {
etag: false,
maxAge: '365 days',
immutable: true,
- // See note about the use of 'fallthrough'
+ // Missing Next assets 404 here.
fallthrough: false,
}),
)
}
- // *** Early exits ***
app.use(shielding)
app.use(handleNextDataPath)
- // *** Security ***
app.use(helmet)
app.use(cookieParser)
app.use(express.json())
if (process.env.NODE_ENV === 'development') {
- app.use(mockVaPortal) // FOR TESTING.
+ app.use(mockVaPortal)
}
- // *** Headers ***
- app.set('etag', false) // We will manage our own ETags if desired
+ app.set('etag', false) // Disable Express ETags so middleware can set them explicitly when needed.
- // *** Config and context for redirects ***
- app.use(urlDecode) // Must come before detectLanguage to decode @ symbols in version segments
- app.use(detectLanguage) // Must come before context, breadcrumbs, find-page, handle-errors, homepages
- app.use(detectVersion) // Must come before handle-redirects for version cookie support
- app.use(asyncMiddleware(reloadTree)) // Must come before context
- app.use(asyncMiddleware(context)) // Must come before early-access-*, handle-redirects
- app.use(shortVersions) // Support version shorthands
- app.use(asyncMiddleware(renderProductName)) // Must come after shortVersions
+ app.use(urlDecode) // Must run before detectLanguage to decode @ symbols in version segments.
+ // Must run before context, breadcrumbs, findPage, handleErrors, and homepages.
+ app.use(detectLanguage)
+ app.use(detectVersion) // Must run before handleRedirects for version cookie support.
+ app.use(asyncMiddleware(reloadTree)) // Must run before context.
+ app.use(asyncMiddleware(context)) // Must run before earlyAccessLinks and handleRedirects.
+ app.use(shortVersions)
+ app.use(asyncMiddleware(renderProductName)) // Must run after shortVersions.
- // Must come before handleRedirects.
- // This middleware might either redirect or serve something.
+ // archivedEnterpriseVersions must run before handleRedirects because it can redirect or serve.
app.use(asyncMiddleware(archivedEnterpriseVersions))
- // *** Redirects, 3xx responses ***
- // I ordered these by use frequency
app.use(trailingSlashes)
- app.use(languageCodeRedirects) // Must come before contextualizers
- app.use(handleRedirects) // Must come before contextualizers
+ app.use(languageCodeRedirects) // Must run before contextualizers.
+ app.use(handleRedirects) // Must run before contextualizers.
- // *** Config and context for rendering ***
- app.use(asyncMiddleware(findPage)) // Must come before archived-enterprise-versions, breadcrumbs, featured-links, products, render-page
+ // Must run before breadcrumbs, featuredLinks, productGroups, and renderPage.
+ app.use(asyncMiddleware(findPage))
app.use(blockRobots)
- // *** Rendering, 2xx responses ***
app.use('/api', api)
app.use('/llms.txt', llmsTxt)
app.get('/_build', buildInfo)
app.get('/_req-headers', reqHeaders)
app.use(asyncMiddleware(manifestJson))
- // Things like `/api` sets their own Fastly surrogate keys.
- // Now that the `req.language` is known, set it for the remaining endpoints
+ // After req.language exists, remaining endpoints get language keys; /api keeps its own.
app.use(setLanguageFastlySurrogateKey)
app.use(robots)
@@ -243,16 +207,14 @@ export default function index(app: Express) {
app.use('/categories.json', asyncMiddleware(categoriesForSupport))
app.get('/_500', asyncMiddleware(triggerError))
- // Specifically deal with HEAD requests before doing the slower
- // full page rendering.
+ // HEAD requests skip slower full page rendering.
app.head('/*path', fastHead)
- // *** Preparation for render-page: contextualizers ***
app.use(asyncMiddleware(dataTables))
app.use(asyncMiddleware(secretScanning))
app.use(asyncMiddleware(ghesReleaseNotes))
app.use(layout)
- app.use(features) // needs to come before product tree
+ app.use(features) // Must run before currentProductTree.
app.use(asyncMiddleware(currentProductTree))
app.use(asyncMiddleware(genericToc))
app.use(breadcrumbs)
@@ -264,18 +226,15 @@ export default function index(app: Express) {
app.use(asyncMiddleware(journeyTrack))
if (ENABLE_FASTLY_TESTING) {
- // The fastlyCacheTest middleware is intended to be used with Fastly to test caching behavior.
- // This middleware will intercept ALL requests routed to it, so be careful if you need to
- // make any changes to the following line:
+ // fastlyCacheTest intercepts all routed requests, so keep the route narrow.
app.use('/fastly-cache-test', fastlyCacheTest)
}
- // handle serving NextJS bundled code (/_next/*)
app.use(next)
- // *** Rendering, must go almost last ***
+ // renderPage must run after specialized routes.
app.get('/*path', asyncMiddleware(renderPage))
- // *** Error handling, must go last ***
+ // handleErrors must run last to catch middleware errors.
app.use(handleErrors)
}
diff --git a/src/frame/middleware/manifest-json.ts b/src/frame/middleware/manifest-json.ts
index 851ca6ce5f11..1e40440f39b1 100644
--- a/src/frame/middleware/manifest-json.ts
+++ b/src/frame/middleware/manifest-json.ts
@@ -30,21 +30,16 @@ export default async function manifestJson(req: Request, res: Response, next: Ne
}
if (req.url !== '/manifest.json') {
- // E.g. `/manifest.json/anything` or `/manifest.json?foo=bar`
+ // Examples: /manifest.json/anything and /manifest.json?foo=bar.
defaultCacheControl(res)
return res.safeRedirect(302, '/manifest.json')
}
const icons: Icon[] = []
- // This is modelled after https://github.com/manifest.json
+ // The manifest mirrors https://github.com/manifest.json.
const manifest = {
- // In the future we might want to have a different manifest for each
- // language. Particularly, the `name` property.
- // But as of May 2023, this is overkill because all translations's
- // home page refer to the name of the site as "GitHub Docs".
- // For example, on https://docs.github.com/ja the ``
- // is "GitHub Docs".
+ // Localized home pages title the site GitHub Docs, so one manifest covers every language.
name: 'GitHub Docs',
short_name: 'GitHub Docs',
start_url: '/',
diff --git a/src/frame/middleware/mock-va-portal.ts b/src/frame/middleware/mock-va-portal.ts
index cafc8781dc4d..be2647716ba9 100644
--- a/src/frame/middleware/mock-va-portal.ts
+++ b/src/frame/middleware/mock-va-portal.ts
@@ -1,15 +1,4 @@
-// Mocks the VA portal so you can test the VA integration without access to a
-// staging VA portal. You can't point at the production one either, because it
-// is hardened to https://docs.github.com and will reject your localhost:4000.
-//
-// To test locally:
-//
-// 1. Add `SUPPORT_PORTAL_URL=http://localhost:4000` to your `.env` file
-// 2. `npm run dev`
-// 3. Navigate to a page listed in the `PagePathToVaFlowMapping` object in
-// the `ArticleContext`.
-//
-// This mocking is not secure. It is only for local development.
+// Local-only Virtual Assistant portal mock; the production portal rejects localhost:4000.
import type { Response, NextFunction } from 'express'
diff --git a/src/frame/middleware/next.ts b/src/frame/middleware/next.ts
index bc50942ffeae..a467ddffc588 100644
--- a/src/frame/middleware/next.ts
+++ b/src/frame/middleware/next.ts
@@ -12,8 +12,7 @@ export const nextHandleRequest = nextApp.getRequestHandler()
await nextApp.prepare()
function renderPageWithNext(req: ExtendedRequest, res: Response, nextFn: NextFunction) {
- // This catches URLs like `/_next/webpack-hmr` and
- // `/_next/static/webpack/64e44ef62e261d3a.webpack.hot-update.json`.
+ // _next asset and HMR requests, like /_next/webpack-hmr, bypass docs routing.
if (req.path.startsWith('/_next') && !req.path.startsWith('/_next/data')) {
return nextHandleRequest(req, res)
}
diff --git a/src/frame/middleware/reload-tree.ts b/src/frame/middleware/reload-tree.ts
index 3007311e64c4..4432194a54dc 100644
--- a/src/frame/middleware/reload-tree.ts
+++ b/src/frame/middleware/reload-tree.ts
@@ -1,13 +1,7 @@
-// This exists for local reviewing only.
-//
-// We load the entire tree on startup and use it for sidebars, breadcrumbs,
-// landing pages, and ToC pages. In development, an individual English page is
-// reread from disk on each request in case it changed, but doing that for all
-// 1k+ pages is not feasible.
-//
-// So this middleware calls `createTree()` with the previous tree, letting
-// `createTree` reuse the pages that haven't changed on disk. That way things
-// like sidebars refresh without restarting the server.
+// The app loads the full tree at startup for sidebars, breadcrumbs, landing pages, and ToC pages.
+// This development-only middleware rereads individual English pages per request.
+// Rereading all 1k+ pages per request would be too slow.
+// createTree receives the previous tree, so navigation refreshes without restarting the server.
import path from 'path'
@@ -27,15 +21,14 @@ const isDev = process.env.NODE_ENV === 'development'
export default async function reloadTree(req: ExtendedRequest, res: Response, next: NextFunction) {
if (!isDev) return next()
- // Filter out things like `/will/redirect` or `/_next/data/...`
+ // Only language-prefixed content paths can refresh the tree; /will/redirect continues.
if (!req.pagePath || !languagePrefixRegex.test(req.pagePath)) return next()
- // We only bother if the loaded URL is something `/en/...`
+ // Only English content can refresh the development tree.
if (!englishPrefixRegex.test(req.pagePath)) return next()
const warmed = await warmServer([])
- // For all the real English content, this usually takes about 30-60ms on
- // an Intel MacBook Pro.
+ // createTree below usually takes 30-60ms for real English content on an Intel MacBook Pro.
const before = getMtimes(warmed.unversionedTree.en)
warmed.unversionedTree.en = (await createTree(
path.join(languages.en.dir, 'content'),
@@ -43,11 +36,7 @@ export default async function reloadTree(req: ExtendedRequest, res: Response, ne
warmed.unversionedTree.en,
)) as UnversionedTree
const after = getMtimes(warmed.unversionedTree.en)
- // The next couple of operations are much slower (in total) than
- // refreshing the tree. So we want to know if the tree changed before
- // bothering.
- // If refreshing of the `.en` part of the `unversionedTree` takes 40ms
- // then the following operations takes about 140ms.
+ // Dependent maps take about 140ms after a 40ms tree refresh, so skip them when mtimes match.
if (before !== after) {
warmed.siteTree = (await loadSiteTree(warmed.unversionedTree)) as SiteTree
warmed.pageList = await loadPages(warmed.unversionedTree)
@@ -58,10 +47,7 @@ export default async function reloadTree(req: ExtendedRequest, res: Response, ne
return next()
}
-// Given a tree, return a number that represents the mtimes for all pages
-// in the tree.
-// You can use this to compute it before and after the tree is (maybe)
-// mutated and if the numbers *change* you can know the tree changed.
+// Summing mtimes lets reloadTree detect page changes before rebuilding slower maps.
function getMtimes(tree: UnversionedTree) {
let mtimes = tree.page.mtime
for (const child of tree.childPages || []) {
diff --git a/src/frame/middleware/render-page.ts b/src/frame/middleware/render-page.ts
index 0aed59fe722e..1d3e0b4b7d2a 100644
--- a/src/frame/middleware/render-page.ts
+++ b/src/frame/middleware/render-page.ts
@@ -27,8 +27,7 @@ async function buildRenderedPage(req: ExtendedRequest): Promise<string> {
if (!page) throw new Error('page not set in context')
const path = req.pagePath || req.path
- // Set up collection array for the collect-mini-toc rehype plugin only when
- // the page actually needs a mini-TOC, avoiding unnecessary work.
+ // Collect mini-TOC headings only for pages that show one, so other renders avoid plugin work.
if (page.showMiniToc) {
const collectMiniToc: CollectedHeading[] = []
context.collectMiniToc = collectMiniToc
@@ -41,16 +40,10 @@ async function buildRenderedPage(req: ExtendedRequest): Promise<string> {
return (await pageRenderTimed(context)) as string
}
-// Spike for #6619: produce the article body as a serializable hast (HTML AST)
-// tree alongside the legacy HTML string.
-//
-// Must run AFTER buildRenderedPage, which calls page.render and populates the
-// context fields the pipeline reads (englishHeadings, alertTitles). We render
-// the same raw `page.markdown`, but with a context clone that omits
-// `collectMiniToc` so the mini-TOC isn't collected a second time.
-//
-// Wrapped so a hast failure can never break the page. The React layer falls
-// back to the string path when this is undefined.
+// buildRenderedPageHast returns a serializable HTML AST alongside renderedPage.
+// It runs after buildRenderedPage because page.render populates englishHeadings and alertTitles.
+// It disables collectMiniToc so mini-TOC collection does not repeat.
+// Failures return undefined, and the React layer falls back to renderedPage.
async function buildRenderedPageHast(req: ExtendedRequest) {
const { context } = req
if (!context) throw new Error('request not contextualized')
@@ -76,12 +69,11 @@ function buildMiniTocItems(req: ExtendedRequest) {
if (!context) throw new Error('request not contextualized')
const { page } = context
- // get mini TOC items on articles
if (!page || !page.showMiniToc) {
return
}
- // Use headings collected during rendering via the collect-mini-toc rehype plugin.
+ // Collected headings avoid rendering article content a second time.
const collected = context.collectMiniToc as CollectedHeading[] | undefined
if (collected) {
return buildMiniTocFromCollected(collected, 2)
@@ -91,15 +83,13 @@ function buildMiniTocItems(req: ExtendedRequest) {
export default async function renderPage(req: ExtendedRequest, res: Response) {
const { context } = req
- // `Error.getInitialProps`, which NextJS runs on errors, reads this off the
- // request so it can send the error to Failbot.
+ // Next.js Error.getInitialProps reads req.FailBot so it can report errors to Failbot.
req.FailBot = FailBot as Failbot
if (!context) throw new Error('request not contextualized')
const { page } = context
const path = req.pagePath || req.path
- // render a 404 page
if (!page) {
if (process.env.NODE_ENV !== 'test' && context.redirectNotFound) {
logger.error('Tried to redirect to a page that was not found', {
@@ -107,27 +97,23 @@ export default async function renderPage(req: ExtendedRequest, res: Response) {
})
}
- // send minimal 404 at this point since we ran into hydration issues trying to pass
- // these along to AppRouter 404 handling
+ // Passing this context to App Router 404 handling causes hydration failures.
defaultCacheControl(res)
return res.status(404).type('html').send(minimumNotFoundHtml)
}
- // Just finish fast without all the details like Content-Length
+ // HEAD skips page rendering but still lets Express send Content-Length: 0.
if (req.method === 'HEAD') {
return res.status(200).send('')
}
- // Updating the Last-Modified header for substantive changes on a page for engineering
- // Docs Engineering Issue #945
+ // effectiveDate marks substantive page changes for clients that watch Last-Modified.
if (page.effectiveDate) {
- // The frontmatter schema only checks that this is a string. An unparseable
- // date gets caught later, in ArticleContext, and ends up as a 500.
+ // ArticleContext turns unparseable effectiveDate strings into a 500.
res.setHeader('Last-Modified', new Date(page.effectiveDate).toUTCString())
}
- // Content negotiation: serve markdown when the client prefers it over HTML.
- // Agents like Claude Code send Accept headers that omit text/html.
+ // Serve markdown when the client prefers it over HTML; agents can omit text/html.
if (req.accepts(['text/html', 'text/markdown']) === 'text/markdown') {
context.markdownRequested = true
}
@@ -137,10 +123,7 @@ export default async function renderPage(req: ExtendedRequest, res: Response) {
if (context.markdownRequested) {
const transformer = transformerRegistry.findTransformer(page)
if (!transformer) throw new Error(`No transformer found for page: ${req.pagePath}`)
- // Pass context without markdownRequested, because transformers set it
- // themselves when rendering templates. Having it set during prepareTemplateData()
- // causes renderTitle/renderProp to output markdown instead of HTML,
- // which breaks the cheerio-based unwrap logic.
+ // Clear markdownRequested so renderTitle and renderProp output HTML for stripOuterTag.
const transformerContext = { ...context, markdownRequested: false }
req.context.renderedPage = normalizeRenderedMarkdown(
await transformer.transform(page, path, transformerContext),
@@ -153,7 +136,6 @@ export default async function renderPage(req: ExtendedRequest, res: Response) {
page.fullTitle = page.title
- // add localized ` - GitHub Docs` suffix to <title> tag (except for the homepage)
if (!patterns.homepagePath.test(path)) {
if (
req.context.currentVersion === 'free-pro-team@latest' ||
@@ -163,9 +145,7 @@ export default async function renderPage(req: ExtendedRequest, res: Response) {
} else {
const { versionTitle } = allVersions[req.context.currentVersion!]
page.fullTitle += ' - '
- // Some plans don't have the word "GitHub" in them.
- // E.g. "Enterprise Server 3.5"
- // In those cases manually prefix the word "GitHub" before it.
+ // Prefix version titles that omit GitHub.
if (!versionTitle.includes('GitHub')) {
page.fullTitle += 'GitHub '
}
@@ -178,15 +158,15 @@ export default async function renderPage(req: ExtendedRequest, res: Response) {
if (isRequestingJsonForDebugging) {
const json = req.query.json
if (Array.isArray(json)) {
- // e.g. ?json=page.permalinks&json=currentPath
+ // Example: ?json=page.permalinks&json=currentPath.
throw new Error("'json' query string can only be 1")
}
if (json) {
- // deep reference: ?json=page.permalinks
+ // Example deep reference: ?json=page.permalinks.
return res.json(get(context, req.query.json as string))
} else {
- // dump all the keys: ?json
+ // Example full key dump: ?json.
return res.json({
message:
'The full context object is too big to display! Try one of the individual keys below, e.g. ?json=page. You can also access nested props like ?json=site.data.reusables',
diff --git a/src/frame/middleware/resolve-carousels.ts b/src/frame/middleware/resolve-carousels.ts
index 2aa68876923b..a69c60253eff 100644
--- a/src/frame/middleware/resolve-carousels.ts
+++ b/src/frame/middleware/resolve-carousels.ts
@@ -6,7 +6,7 @@ import Permalink from '@/frame/lib/permalink'
import { createLogger } from '@/observability/logger/index'
-// The Page class has rawCarousels and carousels properties that aren't on the Page type
+// Page adds rawCarousels and carousels at runtime, but the Page type omits them.
interface PageCarouselProps {
rawCarousels?: Record<string, string[]>
carousels?: Record<string, ResolvedArticle[]>
@@ -20,6 +20,7 @@ function buildArticlePath(currentLanguage: string, articlePath: string, basePath
return `${pathPrefix}${separator}${articlePath}`
}
+// Resolve carousel paths as content-relative, then page-relative, then retry both with .md.
function tryResolveArticlePath(
rawPath: string,
pageRelativePath: string | undefined,
@@ -32,7 +33,6 @@ function tryResolveArticlePath(
return undefined
}
- // Strategy 1: Try content-relative path (add language prefix to raw path)
const contentRelativePath = buildArticlePath(currentLanguage, rawPath)
let foundPage = findPage(contentRelativePath, pages, redirects)
@@ -40,7 +40,6 @@ function tryResolveArticlePath(
return foundPage
}
- // Strategy 2: Try page-relative path if page context is available
if (pageRelativePath) {
const pageDirPath = pageRelativePath.split('/').slice(0, -1).join('/')
const pageRelativeFullPath = buildArticlePath(currentLanguage, rawPath, pageDirPath)
@@ -51,11 +50,9 @@ function tryResolveArticlePath(
}
}
- // Strategy 3: Try with .md extension if not already present
if (!rawPath.endsWith('.md')) {
const pathWithExtension = `${rawPath}.md`
- // Try Strategy 1 with .md extension
const contentRelativePathWithExt = buildArticlePath(currentLanguage, pathWithExtension)
foundPage = findPage(contentRelativePathWithExt, pages, redirects)
@@ -63,7 +60,6 @@ function tryResolveArticlePath(
return foundPage
}
- // Try Strategy 2 with .md extension
if (pageRelativePath) {
const pageDirPath = pageRelativePath.split('/').slice(0, -1).join('/')
const pageRelativeFullPathWithExt = buildArticlePath(
@@ -82,7 +78,6 @@ function tryResolveArticlePath(
return foundPage
}
-// Returns a page's path without the language or version prefix.
function getPageHref(page: Page): string {
if (page.relativePath) {
return Permalink.relativePathToSuffix(page.relativePath)
@@ -137,7 +132,7 @@ async function resolveCarousels(
}
if (resolved.length > 0) {
- // Prevent prototype pollution by rejecting __proto__ keys
+ // Reject unsafe object keys to prevent prototype pollution.
if (
carouselKey !== '__proto__' &&
carouselKey !== 'constructor' &&
diff --git a/src/frame/middleware/robots.ts b/src/frame/middleware/robots.ts
index 11d17680d6f3..137b9ef7d8c9 100644
--- a/src/frame/middleware/robots.ts
+++ b/src/frame/middleware/robots.ts
@@ -17,7 +17,7 @@ export default function robots(req: ExtendedRequest, res: Response, next: NextFu
const host = req.get('x-host') || req.get('x-forwarded-host') || req.get('host')
- // only include robots.txt when it's our production domain and adding localhost for robots-txt.ts test
+ // Allow indexing only on docs.github.com and 127.0.0.1 for tests.
if (
host === 'docs.github.com' ||
req.hostname === 'docs.github.com' ||
diff --git a/src/frame/middleware/safe-redirect.ts b/src/frame/middleware/safe-redirect.ts
index 0c875bfe9ed7..128b0418ec47 100644
--- a/src/frame/middleware/safe-redirect.ts
+++ b/src/frame/middleware/safe-redirect.ts
@@ -2,20 +2,19 @@ import type { Response, NextFunction } from 'express'
import type { ExtendedRequest } from '@/types'
-// Normalizes a redirect URL to prevent open redirects via protocol-relative
-// URLs (e.g. "//evil.com" which browsers interpret as "https://evil.com").
+// Strip protocol-relative prefixes so browsers cannot turn redirects into external URLs.
+// Example: //evil.com becomes /evil.com.
export function safeRedirectUrl(url: string): string {
return url.replace(/^\/\/+/, '/')
}
-// Matches the overloaded signature of Express's res.redirect().
+// SafeRedirect matches the overloaded signature of Express res.redirect.
export type SafeRedirect = {
(url: string): void
(status: number, url: string): void
}
-// Attaches res.safeRedirect() to the response for all downstream middleware.
-// Same signature as res.redirect() but normalizes the URL first.
+// Downstream middleware calls res.safeRedirect with the Express redirect signature.
export default function safeRedirect(req: ExtendedRequest, res: Response, next: NextFunction) {
res.safeRedirect = function (statusOrUrl: number | string, url?: string) {
if (typeof statusOrUrl === 'number' && url !== undefined) {
diff --git a/src/frame/middleware/set-fastly-surrogate-key.ts b/src/frame/middleware/set-fastly-surrogate-key.ts
index a455d661a4f3..23394048441e 100644
--- a/src/frame/middleware/set-fastly-surrogate-key.ts
+++ b/src/frame/middleware/set-fastly-surrogate-key.ts
@@ -3,15 +3,12 @@ import type { Request, Response, NextFunction } from 'express'
import { ExtendedRequest } from '@/types'
import type { Page, Version } from '@/types'
-// Fastly provides a Soft Purge feature that allows you to mark content as outdated (stale) instead of permanently
-// purging and thereby deleting it from Fastly's caches. Objects invalidated with Soft Purge will be treated as
-// outdated (stale) while Fastly fetches a new version from origin.
-//
-// Use of a surrogate key is required for soft purging
+// Fastly soft purges mark cached objects stale while origin fetches a fresh copy.
+// Soft purges require surrogate keys.
// https://docs.fastly.com/en/guides/soft-purges
// https://docs.fastly.com/en/guides/getting-started-with-surrogate-keys
-// What the header needs to be called for Fastly to recognize it.
+// Fastly reads surrogate keys from this response header.
const KEY = 'surrogate-key'
export const SURROGATE_ENUMS = {
@@ -59,16 +56,14 @@ export function makeLanguageSurrogateKey(langCode?: string) {
return `language:${langCode}`
}
-// Build the fine-grained surrogate keys for a content response.
-// A content page is exactly one of each axis, so ~5 keys per page, well under
-// Fastly's 16 KB Surrogate-Key header limit:
-//
-// language:<code> (also emitted for non-content responses)
-// product:<top-level dir> e.g. product:actions (~36)
-// version:<short release slug> e.g. version:ghes-3.14 (~7-8)
-// product:<x>,language:<y> compound, for targeted translation purges
-// language:<code>,path:<path> compound, one key per source page, all versions
-//
+// Content responses get about five keys, one per purge axis,
+// below Fastly's 16 KB header limit.
+// Shapes include language:<code>, product:<top-level-dir>, version:<short-release-slug>,
+// product:<product>,language:<code>, and language:<code>,path:<source-path>.
+// language:<code> also appears on non-content responses.
+// product:<product>,language:<code> targets translation purges.
+// language:<code>,path:<source-path> covers one source page across all versions.
+// Each response emits at most one product key and at most one version key.
export function makeContentSurrogateKeys({
langCode,
productId,
@@ -97,20 +92,19 @@ export function makeContentSurrogateKeys({
return keys
}
-// One surrogate key per source page, e.g. `language:en,path:actions/foo.md`,
-// covering every version-URL of the page. A pure function of language and
-// relativePath so the purge job can rebuild the same key from a changed file's
-// path. Language-scoped so an English deploy doesn't evict translations. Returns
-// undefined for non-content responses.
+// Page surrogate keys cover every version URL for one source page.
+// Example: language:en,path:actions/foo.md.
+// The purge job rebuilds them from changed file paths.
+// Language scoping avoids evicting translations on English deploys.
+// Missing language or path returns undefined for non-content responses.
export function makePageSurrogateKey(langCode?: string, relativePath?: string): string | undefined {
if (!langCode || !relativePath) return undefined
return `language:${langCode},path:${relativePath}`
}
-// Derive the product id for the `product:` surrogate key from a content page's
-// path. The top-level content directory is the product id (mirrors
-// Page.parentProductId), e.g. `actions`. Returns undefined for non-content
-// responses and the top-level homepage (`content/index.md`).
+// Product surrogate keys use the top-level content directory, mirroring Page.parentProductId.
+// Example: actions.
+// Non-content responses and the top-level homepage return undefined.
function productSurrogateId(page?: Page): string | undefined {
const relativePath = page?.relativePath
if (!relativePath) return undefined
@@ -119,10 +113,9 @@ function productSurrogateId(page?: Page): string | undefined {
return id
}
-// Derive the short release slug for the `version:` surrogate key, e.g. `fpt`,
-// `ghec`, `ghes-3.14`. Numbered releases (GHES) get the release appended so a
-// version-scoped purge can target a single release; unnumbered plans use the
-// plain short name.
+// Version surrogate keys use the short name.
+// Numbered GitHub Enterprise Server releases append currentRelease for single-release purges.
+// Unnumbered plans use the short name alone.
function versionSurrogateKey(versionObj?: Version): string | undefined {
if (!versionObj) return undefined
return versionObj.hasNumberedReleases
diff --git a/src/frame/middleware/trailing-slashes.ts b/src/frame/middleware/trailing-slashes.ts
index 53e34ac1856d..cd80572031b9 100644
--- a/src/frame/middleware/trailing-slashes.ts
+++ b/src/frame/middleware/trailing-slashes.ts
@@ -15,7 +15,8 @@ export default function trailingSlashes(req: ExtendedRequest, res: Response, nex
if (split.length) {
url += `?${split.join('?')}`
}
- url = url.replace(/\/+/g, '/') // Prevent multiple slashes
+ // Collapse repeated slashes so the redirect points to one canonical URL.
+ url = url.replace(/\/+/g, '/')
defaultCacheControl(res)
return res.safeRedirect(301, url)
}
diff --git a/src/frame/middleware/url-decode.ts b/src/frame/middleware/url-decode.ts
index 7e49a5e3f86f..ae76a8774b6d 100644
--- a/src/frame/middleware/url-decode.ts
+++ b/src/frame/middleware/url-decode.ts
@@ -1,7 +1,7 @@
import type { NextFunction, Response } from 'express'
import type { ExtendedRequest } from '@/types'
-// Decodes URL-encoded @ symbols anywhere in the URL.
+// Decode URL-encoded @ symbols anywhere in the URL.
// SharePoint and other systems encode @ as %40, which breaks our versioned
// URLs like /en/enterprise-cloud@latest.
export default function urlDecode(req: ExtendedRequest, res: Response, next: NextFunction) {
@@ -16,7 +16,6 @@ export default function urlDecode(req: ExtendedRequest, res: Response, next: Nex
req.url = decodedUrl
return next()
} catch {
- // If decoding fails for any reason, continue with original URL
return next()
}
}
diff --git a/src/frame/pages/app.tsx b/src/frame/pages/app.tsx
index 386c5c496705..4ee1f221fcfe 100644
--- a/src/frame/pages/app.tsx
+++ b/src/frame/pages/app.tsx
@@ -45,11 +45,9 @@ const stagingNames = new Set([
'yew',
])
+// Cache-busting prefixes need any cb-number so Fastly assigns the manual surrogate key.
+// Change the cb number when the image changes, so browsers and the CDN miss the old URL.
function getFaviconHref(stagingName?: string) {
- // The number in these "/cb-xxxxx" prefixes does not matter, it just has to be
- // present. It marks the URL as checksummed, which gets it a manual Fastly
- // surrogate key so a production deploy does not purge it.
- // If you edit these images on disk, change the numbers.
if (stagingName) {
return `/assets/cb-346/images/site/evergreens/${stagingName}.png`
}
@@ -110,12 +108,7 @@ const MyApp = ({ Component, pageProps, languagesContext, stagingName }: MyAppPro
dayScheme={theme.component.dayScheme}
nightScheme={theme.component.nightScheme}
>
- {/*
- Primer Brand ThemeProvider, nested so migrated @primer/react-brand
- components receive brand theme context during the Docs 2026 migration
- (github/docs-engineering#5879). Runs alongside the @primer/react
- ThemeProvider above while the component-by-component swap is in progress.
- */}
+ {/* @primer/react-brand context lets Brand components coexist with @primer/react. */}
<BrandThemeProvider>
<LanguagesContext.Provider value={languagesContext}>
<SharedUIContextProvider>
@@ -131,30 +124,22 @@ const MyApp = ({ Component, pageProps, languagesContext, stagingName }: MyAppPro
MyApp.getInitialProps = async (appContext: AppContext) => {
const { ctx } = appContext
- // calls page's `getInitialProps` and fills `appProps.pageProps`
const appProps = await App.getInitialProps(appContext)
const req = ctx.req as unknown as ExtendedRequest
- // Have to define the type manually here because `req.context.languages`
- // comes from Node JS and is not type-aware.
const languagesContext: LanguagesContextT = {
languages: {},
}
- // If we're rendering certain 404 error pages, the middleware might not
- // yet have contextualized the `context.languages`. So omit this
- // context mutation and live without it.
- // Note, `req` will be undefined if this is the client-side rendering
- // of a 500 page ("Ooops! It looks like something went wrong.")
+ // Some 404 renders lack req.context.languages.
if (req?.context?.languages) {
const languageEntries = Object.entries(req.context.languages as Record<string, LanguageItem>)
for (const [langCode, langObj] of languageEntries) {
- // Only pick out the keys we actually need
languagesContext.languages[langCode] = {
name: langObj.name,
code: langObj.code,
}
- // The `hreflang` is used for the `<link rel="alternate">` tags.
+ // hreflang drives alternate-language link tags.
if (langObj.hreflang && langObj.hreflang !== langObj.code) {
languagesContext.languages[langCode].hreflang = langObj.hreflang
}
diff --git a/src/frame/start-server.ts b/src/frame/start-server.ts
index aa7021dd454a..ec5f6620269e 100644
--- a/src/frame/start-server.ts
+++ b/src/frame/start-server.ts
@@ -1,6 +1,5 @@
-// IMPORTANT: OTel tracing MUST be the first import. It patches Node.js
-// built-ins (http, etc.) at load time via auto-instrumentation.
-// Moving this after any framework import will silently break tracing.
+// Import tracing before framework code so auto-instrumentation can patch Node.js built-ins.
+// Moving it later silently breaks OTel tracing.
import '@/observability/lib/tracing'
import http from 'http'
@@ -44,17 +43,13 @@ async function checkPortAvailability() {
}
}
+// startServer warms the idempotent server cache before listen, so development restarts do not
+// block the first page refresh.
+// The SIGTERM timer forces exit after 25s because the preStop hook sleeps 5s and Kubernetes
+// SIGKILLs at 60s, while the deploy controller can time out on old terminating pods.
async function startServer() {
const app = createApp()
- // Warm up as soon as possible.
- // The `warmServer()` function is idempotent and it will soon be used
- // by some middleware, but there's no point in having a started server
- // without this warmed up. Besides, by starting this slow thing now,
- // it can start immediately instead of waiting for the first request
- // to trigger it to warm up. That way, when in development and triggering
- // a `nodemon` restart, there's a good chance the warm up has come some
- // way before you manage to reach for your browser to do a page refresh.
await warmServer([])
// Workaround for https://github.com/expressjs/express/issues/1101
@@ -65,8 +60,7 @@ async function startServer() {
process.once('SIGTERM', () => {
logger.info('Received SIGTERM, beginning graceful shutdown', { pid: process.pid, port })
- // Force-close idle keep-alive sockets so server.close() doesn't hang
- // waiting for them to disconnect naturally.
+ // Force-close idle keep-alive sockets so server.close() does not wait for natural disconnects.
try {
server.closeIdleConnections()
} catch (err) {
@@ -77,11 +71,6 @@ async function startServer() {
logger.info('HTTP server closed')
})
- // If in-flight requests haven't drained within 25s, force exit.
- // Kubernetes sends SIGKILL at terminationGracePeriodSeconds (60s),
- // but the deploy controller may time out before that if an old pod
- // stays in "Terminating" state too long. The preStop hook sleeps 5s,
- // so 25s here keeps total shutdown well under the 60s grace period.
setTimeout(() => {
logger.warn('Graceful shutdown timed out, forcing exit')
try {
diff --git a/src/frame/stylesheets/article-link-overrides.scss b/src/frame/stylesheets/article-link-overrides.scss
index 47ea20966506..d3519c2ee5dc 100644
--- a/src/frame/stylesheets/article-link-overrides.scss
+++ b/src/frame/stylesheets/article-link-overrides.scss
@@ -1,49 +1,29 @@
-// Docs 2026 article-body link colour, overriding @primer/css's base `a` rule.
+// Docs 2026 article-body links need Brand blue instead of @primer/css accent blue.
//
-// @primer/css/base/base.scss sets
-// a { color: var(--fgColor-accent, var(--color-accent-fg)); }
-// `--fgColor-accent` is defined nowhere in this app except inside a
-// `forced-colors` block, so every link falls through to `--color-accent-fg` and
-// paints Primer's accent blue — #0969da light / #58a6ff dark. That is still the
-// OLD design system's accent; brand ships its own link blue, and the article
-// body is the most visible place the difference shows.
+// @primer/css/base/base.scss sets a to Primer accent blue through --fgColor-accent:
+// #0969da light and #4493f8 dark. Article body links need Brand link blue instead.
//
-// Scoped to `#article-contents[data-article-body] .markdown-body`, matching the
-// scope src/content-render/stylesheets/article-section-framing.scss uses for the
-// article body. All three parts are load-bearing: this stylesheet is global, so
-// a bare `a` rule would repaint the header, sidebar, landings, search and footer
-// as well; `.markdown-body` on its own would still catch the REST / GraphQL /
-// webhook pages that reuse the class; and the id on its own is not enough
-// either, because AutomatedPage renders the same `#article-contents` wrapper for
-// the GraphQL, webhook, audit-log and github-apps pages. The data attribute is
-// set only by ArticlePage and TocLanding.
+// The selector must match src/content-render/stylesheets/article-section-framing.scss:
+// #article-contents[data-article-body] .markdown-body. A bare a rule would repaint the header,
+// sidebar, landings, search, and footer. .markdown-body would also catch REST, GraphQL, and
+// webhook pages. #article-contents would also catch AutomatedPage GraphQL, webhook, audit-log,
+// and github-apps pages. ArticlePage and TocLanding set data-article-body.
#article-contents[data-article-body] .markdown-body {
- // `--brand-color-text-link-*` are the semantic tokens that brand's own
- // InlineLink component aliases into `--brand-InlineLink-color-*`. Using the
- // semantic pair keeps this independent of any ancestor that re-maps the
- // component token — breadcrumbs-overrides.scss does exactly that.
+ // Use --brand-color-text-link-* semantic tokens because breadcrumbs-overrides.scss remaps
+ // --brand-InlineLink-color-* for breadcrumbs.
//
- // Three exclusions, all because this selector outweighs the rules that
- // currently keep those anchors uncoloured:
- // - `[href]` — @primer/css holds `.markdown-body a:not([href])` at
- // `color: inherit`, for the bare named anchors markdown emits.
- // - `:not(.heading-link)` — heading anchors wrap the entire heading text,
- // and headings.scss holds them at `color: unset`.
- // - `:not(.btn)` — CTA buttons in content are plain anchors carrying
- // @primer/css's button classes (`<a class="btn btn-primary">`), so they
- // match this rule too. `.btn-primary`'s own `color` is only (0,1,0)
- // against this selector's (1,4,1), so without the exclusion the label
- // painted brand link-blue on the green button — #005dd5 on #1f883d is
- // 1.31:1, well under the 4.5:1 WCAG AA floor
- // (github/technical-content#7679). Excluding `.btn`
- // hands every button variant back to its own Primer colour tokens.
+ // Exclude anchors that this selector would otherwise override:
+ // a[href] preserves @primer/css .markdown-body a:not([href]) named anchors at color: inherit.
+ // :not(.heading-link) preserves headings.scss, which keeps heading text at color: unset.
+ // :not(.btn) preserves CTA button labels. A .btn-primary label would be #005dd5 on #1f883d,
+ // 1.31:1 contrast, below the 4.5:1 WCAG AA floor.
a[href]:not(.heading-link):not(.btn) {
- // Fallback literals are brand's LIGHT values, not Primer's.
+ // Fallback literals apply only when Brand tokens are undefined.
color: var(--brand-color-text-link-rest, #005dd5);
- // Pressed is brand's only other link colour state. It defines no `:visited`
- // colour, and InlineLink's hover thickens the underline rather than changing
- // colour, so @primer/css's hover underline is left alone.
+ // Pressed is Brand's only other link color state.
+ // Brand has no visited color, and InlineLink only thickens hover underlines.
+ // Leave @primer/css hover behavior unchanged.
&:active {
color: var(--brand-color-text-link-pressed, #002f7a);
}
diff --git a/src/frame/stylesheets/breadcrumbs-overrides.scss b/src/frame/stylesheets/breadcrumbs-overrides.scss
index 9f04809032d7..743bce5fdb65 100644
--- a/src/frame/stylesheets/breadcrumbs-overrides.scss
+++ b/src/frame/stylesheets/breadcrumbs-overrides.scss
@@ -1,31 +1,21 @@
-// Docs 2026 breadcrumb treatment, overriding @primer/react-brand's Breadcrumbs.
+// Docs 2026 breadcrumbs invert @primer/react-brand default emphasis.
//
-// Brand's `default` variant renders the ancestor crumbs at full strength and
-// MUTES the current page. The design wants the inverse: the pages you are not
-// viewing — and the "/" separators between them — recede, while the page you're
-// on reads at full strength.
+// Brand's default variant gives ancestor crumbs full strength and mutes the current page. The
+// design needs ancestor pages and "/" separators to recede while the current page stays full
+// strength.
//
-// Keyed off the `data-container` attribute rather than a class because brand's
-// Breadcrumbs <nav> discards any className passed to it, so there is no class
-// hook on that element. The element selectors (`nav`, `li`) are here to out-
-// weigh brand's own rules, which are applied through the component's CSS module
-// and can load after this stylesheet — specificity, rather than source order,
-// is what keeps these overrides winning.
+// Use data-container because Brand Breadcrumbs nav drops className, so no class hook reaches that
+// element. The nav and li selectors raise specificity above Brand CSS modules that can load later.
nav[data-container="breadcrumbs"] {
- // Match the type of the SELECTED doc-tree nav item exactly. Brand already
- // sizes crumbs at 14px/400 (text-size-100) but leaves letter-spacing unset,
- // where the NavList item carries the 100-scale value.
+ // Match the selected doc-tree nav item type: 14px/400 plus 100-scale letter spacing.
letter-spacing: var(--brand-text-letterSpacing-100);
- // Ancestor crumbs (still links) and the separator rules recede. The separator
- // is drawn as a rotated border on `li::after`, so it reads this token rather
- // than `color`.
+ // Ancestor links and separators recede. li::after draws separators as a rotated border.
--brand-InlineLink-color-rest: var(--brand-color-text-muted);
--brand-InlineLink-color-pressed: var(--brand-color-text-muted);
--brand-breadcrumbs-separator-borderColor: var(--brand-color-text-muted);
- // The current page reads at full strength. Brand's default variant explicitly
- // mutes this one, so this needs to outweigh a two-class selector.
+ // The current page needs more specificity than Brand's two-class selector.
li [aria-current="page"] {
color: var(--brand-color-text-default);
}
diff --git a/src/frame/stylesheets/dialog-overrides.scss b/src/frame/stylesheets/dialog-overrides.scss
index 4401dcd0e78d..1f32f8305af5 100644
--- a/src/frame/stylesheets/dialog-overrides.scss
+++ b/src/frame/stylesheets/dialog-overrides.scss
@@ -1,7 +1,7 @@
@import "breakpoint-xxl.scss";
#__primerPortalRoot__ [class*="prc-Dialog-Backdrop"] {
- /* Make sure the dialog backdrop is hidden on large screens */
+ /* The XXL breakpoint below hides the dialog backdrop on large screens. */
display: flex;
visibility: visible;
@@ -11,7 +11,7 @@
}
}
-// Fix z-index for ActionMenu overlays (version picker, etc.) to appear above site header
+// Keep ActionMenu overlays, including the version picker, above the site header.
#__primerPortalRoot__ * {
z-index: 3 !important;
}
diff --git a/src/frame/stylesheets/index.scss b/src/frame/stylesheets/index.scss
index f2e1ea2ed82e..50bc17542340 100644
--- a/src/frame/stylesheets/index.scss
+++ b/src/frame/stylesheets/index.scss
@@ -1,38 +1,32 @@
-@import "@primer/css/color-modes/index.scss"; // Must come first
-@import "@primer/css/core/index.scss"; // Must come second
+@import "@primer/css/color-modes/index.scss"; // Color modes must load before core.
+@import "@primer/css/core/index.scss"; // Core must load before component styles.
-// Primer Primitives functional themes.
+// Primer functional theme tokens bridge @primer/css and @primer/react.
//
-// @primer/css@21 only defines the legacy `--color-*` names (it pins its own
-// nested @primer/primitives@7). @primer/react@38's component CSS, and a lot of
-// our own SCSS, reference the newer `--fgColor-*` / `--bgColor-*` /
-// `--borderColor-*` / `--button-*` names instead — and nothing in this app
-// defined them. An undefined custom property makes the whole declaration
-// invalid at computed-value time, so those rules either dropped out entirely
-// (`border: 1px solid var(--borderColor-default)` painted no border at all) or
-// fell through to a hardcoded light-mode hex that then won in BOTH modes.
-// That is why PRC components rendered light-grey icons in dark mode.
+// @primer/css defines legacy --color-* names, while @primer/react and this SCSS reference newer
+// --fgColor-*, --bgColor-*, --borderColor-*, and --button-* names. Missing custom properties
+// invalidate whole declarations at computed-value time, which drops rules or falls through to
+// hardcoded light-mode hex values in both modes. Primer React components then render light-grey
+// icons in dark mode.
//
-// Scoped by [data-color-mode]/[data-*-theme] exactly like the @primer/css
-// themes above, so only the active theme's block applies. Limited to the four
-// themes `SupportedTheme` actually allows (see src/color-schemes).
+// Scope these imports by [data-color-mode] and [data-*-theme] like @primer/css themes, so only
+// the active theme block applies. Limit them to the four themes SupportedTheme allows in
+// src/color-schemes.
@import "@primer/primitives/dist/css/functional/themes/light.css";
@import "@primer/primitives/dist/css/functional/themes/dark.css";
@import "@primer/primitives/dist/css/functional/themes/dark-dimmed.css";
@import "@primer/primitives/dist/css/functional/themes/dark-high-contrast.css";
-// Primer components
@import "@primer/css/markdown/index.scss";
@import "@primer/css/labels/index.scss";
@import "@primer/css/alerts/index.scss";
@import "@primer/css/popover/index.scss";
-// Primer Brand design system (Docs 2026 migration — github/docs-engineering#5879).
+// Primer Brand design system for the Docs 2026 migration.
// Loaded alongside @primer/css during the incremental component-by-component swap.
@import "@primer/react-brand/lib/css/main.css";
-// Registers the Mona Sans / Hubot Sans @font-face rules (+ metric-adjusted
-// fallbacks) that back the brand `--brand-*-fontFamily` tokens. Without this,
-// those tokens silently fall back to the system font stack.
+// Registers the Mona Sans and Hubot Sans font-face rules plus metric-adjusted fallbacks that back
+// the Brand fontFamily tokens. Without this, those tokens silently fall back to the system stack.
@import "@primer/react-brand/fonts/fonts.css";
@import "headings.scss";
@@ -45,58 +39,39 @@
@import "src/content-render/stylesheets/index.scss";
@import "src/links/stylesheets/hover-card.scss";
-// For primer Spinners and other animated components
@import "@primer/primitives/dist/css/base/motion/motion.css";
-// Docs 2026: Primer Brand owns the page canvas.
+// Primer Brand owns the page canvas.
//
-// `@primer/css/base/native-colors.scss` paints both `body` and *every*
-// `[data-color-mode]` element from the Primer Component palette:
+// @primer/css/base/native-colors.scss paints body and every [data-color-mode] element from the
+// Primer Component palette. @primer/react ThemeProvider renders a wrapper div with
+// data-color-mode, while src/color-schemes/components/BrandThemeProvider.tsx does not, so that
+// wrapper would paint Primer's canvas. In dark mode that canvas is #0d1117, while migrated Brand
+// surfaces sit on #000000 or #0f1511. #0f1511 on #0d1117 is 1.02:1.
//
-// [data-color-mode] {
-// color: var(--fgColor-default, var(--color-fg-default));
-// background-color: var(--bgColor-default, var(--color-canvas-default));
-// }
+// Repoint the root canvas at Brand so migrated surfaces read together. Primer-palette subtle fills
+// #161b22 and borders #30363d remain visible above true black.
//
-// @primer/react's `ThemeProvider` renders a real wrapping `<div data-color-mode>`
-// (brand's no longer does; see src/color-schemes/components/BrandThemeProvider.tsx),
-// so it matched that selector and painted itself Primer's canvas. In dark mode
-// that is #0d1117 — a
-// blue-tinted charcoal — while every surface migrated to Brand tokens sits on
-// Brand's true black (#000000) or its green-tinted near-black (#0f1511). The
-// result was up to three different "blacks" stacked on one page, and fills
-// meant to read as a lift above the page instead read as an invisible dip below
-// it (#0f1511 on #0d1117 is 1.02:1).
-//
-// Repointing the canvas at Brand is what makes the migrated surfaces cohere.
-// Primer-palette components layered on top still read correctly, because their
-// subtle fills (#161b22) and borders (#30363d) become lifts above true black
-// rather than clashing steps beside it.
-//
-// The canvas is decided at the ROOT, and only at the root. `<html>` is the one
-// element whose `data-color-mode` is correct before first paint: colorModeScript
-// (src/color-schemes/lib/color-mode-script.ts) stamps it from the cookie
-// synchronously in <head>. The SSR markup cannot carry the user's real mode,
-// because that HTML is shared-cacheable in the CDN and must be identical for
-// every request.
+// Only the root decides the canvas. html carries the correct data-color-mode before first paint
+// because src/color-schemes/lib/color-mode-script.ts stamps it from the cookie in head. SSR cannot
+// carry the user's mode because shared CDN HTML must stay identical for every request.
html[data-color-mode],
html[data-color-mode] body {
background-color: var(--brand-color-canvas-default);
color: var(--brand-color-text-default);
}
-// ...and every NESTED [data-color-mode] wrapper stays transparent so the root
-// canvas shows through — @primer/react's ThemeProvider still renders one. Never
-// a `--brand-*` token here: a nested wrapper re-declares brand's palette and
-// would paint its own mode, not the page's. `:not(html)` adds html's (0,0,1) to
-// beat @primer/css's `[data-color-mode]` (0,1,0).
+// Nested [data-color-mode] wrappers stay transparent so the root canvas shows through.
+// @primer/react ThemeProvider still renders one. Never use a --brand-* token here: a nested
+// wrapper re-declares Brand's palette and would paint its own mode instead of the page mode.
+// :not(html) adds html specificity to beat @primer/css [data-color-mode] at 0,1,0.
[data-color-mode]:not(html) {
background-color: transparent;
color: inherit;
}
-// No-JS fallback, not dead code: without the pre-paint script <html> keeps the
-// SSR `auto` default, which @primer/primitives honours and brand does not.
+// No-JS fallback: without the pre-paint script, html keeps the SSR auto default, which
+// @primer/primitives honors and Brand does not.
@media (prefers-color-scheme: dark) {
html[data-color-mode="auto"][data-dark-theme*="dark"] {
--brand-color-canvas-default: var(--base-color-scale-black-0);
@@ -118,24 +93,19 @@ html[data-color-mode] body {
}
}
-// Docs 2026: links use Brand's link colour.
+// Site-wide links use Brand link blue.
//
-// `@primer/css/base/base.scss` sets `a { color: var(--fgColor-accent, …) }` —
-// Primer's blue (#0969da light / #4493f8 dark). Brand's link blue is a
-// different value (#0055d5 light / #a2daff dark) and is what the migrated
-// surfaces are designed around. `.markdown-body` does not set its own anchor
-// colour, so prose links inherit this too.
+// @primer/css/base/base.scss sets a color to var(--fgColor-accent, ...) values: #0969da light and
+// #4493f8 dark. Brand link blue is #0055d5 light and #a2daff dark. Migrated surfaces use Brand
+// colors, and .markdown-body prose links inherit this rule.
//
-// Specificity is deliberately left at (0,0,1) to exactly match the rule this
-// replaces. Anything more specific — `a[href]`, say — would start winning
-// against component classes like `.prc-Button-*` (0,1,0) and repaint PRC
-// buttons that happen to render as anchors. This is a value swap, not a
-// cascade change; primer's own `a:not([href])` carve-outs still apply.
+// Keep specificity at 0,0,1 to match the rule this replaces. More specificity, such as a[href],
+// would win against component classes like .prc-Button-* at 0,1,0 and repaint PRC buttons that
+// render as anchors. This swaps the value without changing the cascade, so @primer/css
+// a:not([href]) carve-outs still apply.
//
-// article-link-overrides.scss layers a much more specific rule over the article
-// body for the same token. That is not redundant: it adds the `:active` pressed
-// state and deliberately exempts `.heading-link` and bare named anchors. This
-// rule is the site-wide base; that one is the article body's specialisation.
+// article-link-overrides.scss layers a more specific rule over the article body for the same token.
+// It adds the :active pressed state and exempts .heading-link, .btn, and bare named anchors.
a {
color: var(--brand-color-text-link-rest);
}
diff --git a/src/frame/stylesheets/scroll-top.scss b/src/frame/stylesheets/scroll-top.scss
index 4645b5ff64eb..f7c3f93d1a1e 100644
--- a/src/frame/stylesheets/scroll-top.scss
+++ b/src/frame/stylesheets/scroll-top.scss
@@ -1,10 +1,9 @@
@import "src/frame/stylesheets/breakpoint-xxl.scss";
-// Mirrors Brand's SubdomainNavBar height so every sticky offset tracks the real
-// header. Brand defines that height in rem -- `--base-size-64` (4rem), reduced by
-// `--base-size-8` (0.5rem) below its `medium` breakpoint of 47.99rem -- so these
-// must be rem too. A px value with a px breakpoint silently drifts from the
-// actual header for any reader whose browser default font size is not 16px.
+// Brand SubdomainNavBar height uses rem, so the header portion of sticky offsets must use rem too.
+// Brand sets --base-size-64 at 4rem and subtracts --base-size-8, 0.5rem, below its medium
+// breakpoint of 47.99rem. A px value or px breakpoint drifts when readers change the browser
+// default font size.
:root {
--docs-header-height: 3.5rem;
@@ -21,6 +20,6 @@
@include breakpoint-xxl {
scroll-margin-top: calc(
var(--docs-header-height) + 44px
- ) !important; // Header + secondary bar
+ ) !important; // Include the secondary bar below the header.
}
}
diff --git a/src/frame/stylesheets/utilities.scss b/src/frame/stylesheets/utilities.scss
index 38d550bc3949..5bf4343df673 100644
--- a/src/frame/stylesheets/utilities.scss
+++ b/src/frame/stylesheets/utilities.scss
@@ -37,7 +37,7 @@
width: 1px;
}
-// For the screenreader
+// Screen readers and keyboard users need a visible skip link on focus.
.skip-button {
width: auto;
height: auto;
@@ -56,7 +56,7 @@
}
}
-// used to help prevent overlapping main content and the minitoc sidebar
+// Avoid overlapping main content and the mini TOC sidebar at XXL widths.
.d-xxl-block {
@include breakpoint-xxl {
display: block !important;
diff --git a/src/frame/tests/content.ts b/src/frame/tests/content.ts
index 0e145e55e82e..31e3efc9cc9f 100644
--- a/src/frame/tests/content.ts
+++ b/src/frame/tests/content.ts
@@ -36,7 +36,7 @@ describe('content files', () => {
const orphanedFiles = contentFiles.filter((file) => !relativeFiles.includes(file))
- // Filter out intentional test fixture files that are meant to be orphaned
+ // These fixture files intentionally stay outside the tree.
const allowedOrphanedFiles = [
path.join(contentDir, 'article-one.md'),
path.join(contentDir, 'article-two.md'),
diff --git a/src/frame/tests/fetch-utils.test.ts b/src/frame/tests/fetch-utils.test.ts
index c98addc7aa7a..2bdfb82ef29f 100644
--- a/src/frame/tests/fetch-utils.test.ts
+++ b/src/frame/tests/fetch-utils.test.ts
@@ -85,8 +85,7 @@ describe('fetchWithRetry ttfb timeout mode', () => {
await fetchWithRetry('https://example.test/big', {}, { timeout: 10, timeoutMode: 'ttfb' })
- // Wait well past the TTFB deadline; the timer must have been cleared so the
- // signal stays unaborted and a subsequent body read wouldn't be cut off.
+ // Wait past the TTFB deadline to prove response resolution cleared the timer.
await new Promise((resolve) => setTimeout(resolve, 40))
expect(capturedSignal?.aborted).toBe(false)
expect(statsdIncrement).not.toHaveBeenCalled()
@@ -197,9 +196,7 @@ describe('fetchStream timeout mode', () => {
await fetchStream('https://example.test/stream', {}, { timeout: 10, throwHttpErrors: false })
- // A streaming caller reads the body well past the connect deadline. With the
- // ttfb default the timer is cleared on response-resolve, so the signal stays
- // unaborted and a long-running reader.read() loop won't be cut off.
+ // Wait past the TTFB deadline to prove response resolution cleared the default timer.
await new Promise((resolve) => setTimeout(resolve, 40))
expect(capturedSignal?.aborted).toBe(false)
expect(statsdIncrement).not.toHaveBeenCalled()
diff --git a/src/frame/tests/find-page-middleware.ts b/src/frame/tests/find-page-middleware.ts
index ab42f6d23883..9aa21f4047a5 100644
--- a/src/frame/tests/find-page-middleware.ts
+++ b/src/frame/tests/find-page-middleware.ts
@@ -127,8 +127,7 @@ describe('find page middleware', () => {
})
test("will 404 if the request version doesn't match the page", async () => {
- // The 'versions:' frontmatter on 'page-with-redirects.md' does
- // not include ghes. So this'll eventually 404.
+ // page-with-redirects.md excludes GHES, so enterprise-server@latest eventually 404s.
const [req, res] = makeRequestResponse('/en/page-with-redirects', 'enterprise-server@latest')
const page = await Page.init({
relativePath: 'page-with-redirects.md',
diff --git a/src/frame/tests/get-remote-json.ts b/src/frame/tests/get-remote-json.ts
index 5f1270ef0b09..87e0e639ca0e 100644
--- a/src/frame/tests/get-remote-json.ts
+++ b/src/frame/tests/get-remote-json.ts
@@ -7,8 +7,7 @@ import nock from 'nock'
import getRemoteJSON, { cache } from '@/frame/lib/get-remote-json'
-// Covers the in-memory cache, and the fallback to the disk cache when memory
-// misses.
+// Covers in-memory caching and disk-cache fallback after a memory miss.
describe('getRemoteJSON', () => {
const envVarValueBefore = process.env.GET_REMOTE_JSON_DISK_CACHE_ROOT
@@ -34,8 +33,7 @@ describe('getRemoteJSON', () => {
const data = await getRemoteJSON(url, {})
expect((data as Record<string, unknown>).foo).toBe('bar')
expect(cache.get(url)).toBeTruthy()
- // Second time, despite not setting up a second nock(), will work
- // because it can use memory now.
+ // A second network request would fail unless getRemoteJSON uses the memory cache.
const data2 = await getRemoteJSON(url, {})
expect((data2 as Record<string, unknown>).foo).toBe('bar')
expect(cache.get(url)).toBeTruthy()
@@ -50,9 +48,7 @@ describe('getRemoteJSON', () => {
expect(cache.get(url)).toBeTruthy()
cache.delete(url)
- // This time, the nock won't fail despite not using `.persist()`.
- // That means it didn't need the network because it was able to
- // use the disk cache.
+ // A second network request would fail unless getRemoteJSON uses the disk cache.
const data2 = await getRemoteJSON(url, {})
expect((data2 as Record<string, unknown>).cool).toBe(true)
})
@@ -70,8 +66,7 @@ describe('getRemoteJSON', () => {
}
cache.delete(url)
- // If we don't do this, nock will fail because a second network
- // request became necessary.
+ // A second nock response lets getRemoteJSON recover after the corrupted disk cache misses.
nock(origin).get(pathname).reply(200, { cool: true })
const data = await getRemoteJSON(url, {})
@@ -92,8 +87,7 @@ describe('getRemoteJSON', () => {
}
cache.delete(url)
- // If we don't do this, nock will fail because a second network
- // request became necessary.
+ // A second nock response lets getRemoteJSON recover after the corrupted disk cache misses.
nock(origin).get(pathname).reply(200, { cool: true })
const data = await getRemoteJSON(url, {})
diff --git a/src/frame/tests/manifest.ts b/src/frame/tests/manifest.ts
index 4582d1087d3f..88d5d1211dbd 100644
--- a/src/frame/tests/manifest.ts
+++ b/src/frame/tests/manifest.ts
@@ -26,7 +26,7 @@ describe('manifest', () => {
const res = await get(url)
expect(res.statusCode).toBe(200)
- // Check that it can be cached at the CDN
+ // CDN caching must not set cookies and must include the no-language surrogate key.
expect(res.headers['set-cookie']).toBeUndefined()
expect(res.headers['cache-control']).toContain('public')
expect(res.headers['cache-control']).toMatch(/max-age=[1-9]/)
@@ -45,7 +45,7 @@ describe('manifest', () => {
const iconRes = await get(icon.src, { responseType: 'buffer' })
expect(iconRes.statusCode).toBe(200)
expect(iconRes.headers['content-type']).toBe(icon.type)
- // The `sizes` should match the payload
+ // sizes must match the image payload.
const image = sharp(iconRes.body)
const [width, height] = icon.sizes.split('x').map((s) => parseInt(s))
const dimensions = await image.metadata()
diff --git a/src/frame/tests/mini-toc-items.ts b/src/frame/tests/mini-toc-items.ts
index 3b43d011f62f..a8ea0eead14b 100644
--- a/src/frame/tests/mini-toc-items.ts
+++ b/src/frame/tests/mini-toc-items.ts
@@ -28,18 +28,7 @@ describe('buildMiniTocFromCollected', () => {
expect(tocItems[0].items?.length).toBe(3)
})
- /**
- * Mock scenario from: /en/rest/reference/apps
- * The TOC starts out with lower importance headers that aren't nested in
- * higher importance headers
- *
- * 3
- * 3
- * 2
- * 3
- * 2
- * 3
- */
+ // /en/rest/reference/apps begins with unnested levels 3, 3, then continues 2, 3, 2, 3.
test('creates toc that starts with lower importance headers', () => {
const collected = [
heading('section-1-A', 3),
@@ -54,8 +43,7 @@ describe('buildMiniTocFromCollected', () => {
expect(tocItems[3].items?.length).toBe(1)
})
- // Mock scenario from:
- // /en/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization
+ // Scenario from: /en/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization
test('creates empty toc', () => {
const tocItems = buildMiniTocFromCollected([], 3)
expect(tocItems.length).toBe(0)
diff --git a/src/frame/tests/non-child-pages-resolution.test.ts b/src/frame/tests/non-child-pages-resolution.test.ts
index 47fe3c6fd6e9..ec1bb1fc841b 100644
--- a/src/frame/tests/non-child-pages-resolution.test.ts
+++ b/src/frame/tests/non-child-pages-resolution.test.ts
@@ -4,13 +4,11 @@ import fs from 'fs'
const ROOT = path.resolve(__dirname, '../../..')
-// Tests for non-child page resolution: a `/content/` prefix in children
-// frontmatter resolves to an absolute content path, which is what lets a page
-// pull in a directory or article from another product.
+// Tests for non-child page resolution: /content/ in children frontmatter resolves to an absolute
+// content path, so a page can pull in a directory or article from another product.
//
-// Note this file imports no production code. The behaviour tests reimplement
-// logic from create-tree.ts and current-product-tree.ts, and the rest only check
-// that fixture files exist, so none of it exercises the real resolution path.
+// This file imports no production code. Behavior tests reimplement logic from create-tree.ts and
+// current-product-tree.ts, and the rest only check fixtures, so none exercises the real path.
describe('Non-child page resolution', () => {
describe('/content/ prefix in children frontmatter', () => {
@@ -34,7 +32,6 @@ describe('Non-child page resolution', () => {
const basePath = '/Users/test/docs-internal/content'
const child = '/content/actions/workflows'
- // Simulate the logic from create-tree.ts
let childPath: string
if (child.startsWith('/content/')) {
const absoluteChildPath = child.slice('/content/'.length)
@@ -50,7 +47,6 @@ describe('Non-child page resolution', () => {
const basePath = '/Users/test/docs-internal/content'
const child = '/content/get-started/foo/bar'
- // Simulate the logic from create-tree.ts
let childPath: string
if (child.startsWith('/content/')) {
const absoluteChildPath = child.slice('/content/'.length)
@@ -66,7 +62,6 @@ describe('Non-child page resolution', () => {
const originalPath = '/Users/test/docs-internal/content/get-started'
const child = '/local-child'
- // Simulate the logic from create-tree.ts
let childPath: string
if (child.startsWith('/content/')) {
const absoluteChildPath = child.slice('/content/'.length)
@@ -143,8 +138,7 @@ describe('Non-child page resolution', () => {
describe('translation behavior', () => {
test('cross-product children paths are language-agnostic', () => {
- // The /content/ prefix paths should work regardless of the current language
- // The actual translation is handled by the page loading system
+ // Translation happens after /content/ cross-product path resolution.
const child = '/content/actions/using-workflows/storing-workflow-data-as-artifacts'
expect(child.startsWith('/content/')).toBe(true)
@@ -152,8 +146,7 @@ describe('Non-child page resolution', () => {
})
test('resolved paths use content directory, not translations', () => {
- // Cross-product children are resolved from the main content directory
- // Translations are handled separately by the page rendering system
+ // Cross-product children resolve from the main content directory before translations apply.
const basePath = '/Users/test/docs-internal/content'
const child = '/content/actions/workflows'
@@ -165,7 +158,6 @@ describe('Non-child page resolution', () => {
describe('crossProductChild flag', () => {
test('flag is set for /content/ prefix paths', () => {
- // Simulate the logic from create-tree.ts
const child = '/content/actions/workflows'
const isCrossProduct = child.startsWith('/content/')
expect(isCrossProduct).toBe(true)
@@ -178,7 +170,6 @@ describe('Non-child page resolution', () => {
})
test('crossProductChild flag excludes items from sidebar', () => {
- // Simulate the sidebarTree filtering logic
const childPages = [
{ href: '/en/get-started/foo', title: 'Foo', crossProductChild: false },
{ href: '/en/actions/workflows', title: 'Workflows', crossProductChild: true },
@@ -192,11 +183,8 @@ describe('Non-child page resolution', () => {
})
describe('descendant-of-sibling filtering in sidebar', () => {
+ // When a bespoke landing page lists a parent group and its articles, the sidebar drops those articles.
test('filters out children that are descendants of another sibling', () => {
- // Simulate the sidebarTree descendant filtering logic.
- // When a bespoke landing page lists both individual articles and their
- // parent group as children, the individual articles should be filtered out
- // from the sidebar (they appear nested under their parent group instead).
const childPages = [
{
href: '/en/get-started/copilot/add-custom-instructions',
@@ -212,13 +200,11 @@ describe('Non-child page resolution', () => {
(child) => !siblingHrefs.some((sh) => sh !== child.href && child.href.startsWith(`${sh}/`)),
)
- // The two individual articles under /copilot/ should be removed
expect(dedupedChildPages).toHaveLength(2)
expect(dedupedChildPages.map((c) => c.title)).toEqual(['Copilot', 'Actions'])
})
test('does not filter children that are not descendants of any sibling', () => {
- // Normal case: no overlapping paths, nothing should be filtered
const childPages = [
{ href: '/en/get-started/copilot', title: 'Copilot' },
{ href: '/en/get-started/actions', title: 'Actions' },
@@ -234,7 +220,6 @@ describe('Non-child page resolution', () => {
})
test('handles multiple overlapping groups correctly', () => {
- // Multiple groups each with their own individual articles listed
const childPages = [
{ href: '/en/get-started/copilot/article-a', title: 'Article A' },
{ href: '/en/get-started/copilot', title: 'Copilot' },
diff --git a/src/frame/tests/page.ts b/src/frame/tests/page.ts
index bebcd92e1960..7e14641ed98d 100644
--- a/src/frame/tests/page.ts
+++ b/src/frame/tests/page.ts
@@ -23,7 +23,6 @@ const enterpriseServerVersions = Object.keys(allVersions).filter((v) =>
v.startsWith('enterprise-server@'),
)
-// get the `free-pro-team` segment of `free-pro-team@latest`
const nonEnterpriseDefaultPlan = nonEnterpriseDefaultVersion.split('@')[0]
const opts = {
@@ -80,9 +79,7 @@ describe('Page class', () => {
})
describe('page.render(context)', () => {
- // Most of our Liquid versioning tests are in https://github.com/docs/render-content,
- // But they don't have access to our currently supported versions, which we're testing here.
- // This test ensures that this works as expected: {% if enterpriseServerVersions contains currentVersion %}
+ // Test {% if enterpriseServerVersions contains currentVersion %} here; docs/render-content lacks version data.
test('renders the expected Enterprise Server versioned content', async () => {
const page = await Page.init({
relativePath: 'page-versioned-for-all-enterprise-releases.md',
@@ -104,8 +101,7 @@ describe('Page class', () => {
'This text should only render on non-Enterprise',
)
- // change version to the oldest enterprise version, re-render, and test again;
- // the results should be the same
+ // Re-render with the oldest Enterprise Server version; the text must stay the same.
context.currentVersion = `enterprise-server@${enterpriseServerReleases.oldestSupported}`
context.currentPath = `/${context.currentLanguage}/${context.currentVersion}/${page!.relativePath}`
rendered = await page!.render(context)
@@ -117,8 +113,7 @@ describe('Page class', () => {
'This text should only render on non-Enterprise',
)
- // change version to non-enterprise, re-render, and test again;
- // the results should be the opposite
+ // Re-render with the non-enterprise version; the text must invert.
context.currentVersion = nonEnterpriseDefaultVersion
context.currentPath = `/${context.currentLanguage}/${context.currentVersion}/${page!.relativePath}`
rendered = await page!.render(context)
@@ -325,37 +320,17 @@ describe('Page class', () => {
expect(page!.versions.ghes).toBe('*')
})
+ // Feature versions must combine with frontmatter versions so latest GHES remains applicable.
test('feature versions frontmatter', async () => {
- // This fixture file has the frontmatter:
- //
- // versions:
- // fpt: '*'
- // ghes: '*'
- // feature: 'placeholder'
- //
- // and placeholder.yml has:
- //
- // versions:
- // ghes: '<3.0'
- //
- // So we expect to get the versioning from both.
const page = await Page.init({
relativePath: 'feature-versions-frontmatter.md',
basePath: path.join(__dirname, '../../../src/fixtures/fixtures'),
languageCode: 'en',
})
- // Test the raw page data.
expect(page!.versions.fpt).toBe('*')
expect(page!.versions.ghes).toBe('>2.21')
- // Test the resolved versioning, where GHES releases specified in frontmatter and in
- // feature versions are combined (i.e., one doesn't overwrite the other).
- // We can't test that GHES 2.21 is _not_ included here (which it shouldn't be),
- // because lib/get-applicable-versions only returns currently supported versions,
- // so as soon as 2.21 is deprecated, a test for that _not_ to exist will not be meaningful.
- // But by testing that the _latest_ GHES version is returned, we can ensure that the
- // the frontmatter GHES `*` is not being overwritten by the placeholder's GHES `<3.0`.
expect(page!.applicableVersions.includes('free-pro-team@latest')).toBe(true)
expect(page!.applicableVersions.includes(`enterprise-server@${latest}`)).toBe(true)
expect(page!.applicableVersions.includes('feature')).toBe(false)
@@ -469,7 +444,6 @@ describe('catches errors thrown in Page class', () => {
expect(page!.product).toBe('')
expect(page!.permissions).toBe('')
- // Change to FPT
context.page.version = nonEnterpriseDefaultVersion
context.version = nonEnterpriseDefaultVersion
context.currentPath = '/en/optional/attributes'
diff --git a/src/frame/tests/pages.ts b/src/frame/tests/pages.ts
index 913c49cd5364..7827708918a3 100644
--- a/src/frame/tests/pages.ts
+++ b/src/frame/tests/pages.ts
@@ -57,7 +57,7 @@ describe('pages module', () => {
const redirectToFiles = new Map<string, Set<string>>()
const versionedRedirects: Array<{ path: string; file: string }> = []
- // Page objects have dynamic properties from chain/lodash that aren't fully typed
+ // lodash pick loses the concrete Page fields that the redirect loop needs.
for (const page of englishPages) {
const pageObj = page as Record<string, unknown>
for (const redirect of pageObj.redirect_from as string[]) {
@@ -72,7 +72,7 @@ describe('pages module', () => {
}
}
- // Only consider as duplicate if more than one unique file defines the same redirect
+ // A redirect duplicates only when more than one file defines it.
const duplicates = Array.from(redirectToFiles.entries())
.filter(([, files]) => files.size > 1)
.map(([redirectPath]) => redirectPath)
@@ -93,15 +93,15 @@ describe('pages module', () => {
.filter((page) => {
slugger.reset()
return (
- page.languageCode === 'en' && // only check English
- !page.relativePath.includes('index.md') && // ignore TOCs
- // Page class has dynamic frontmatter properties like 'allowTitleToDifferFromFilename' not in type definition
- !(page as Record<string, unknown>).allowTitleToDifferFromFilename && // ignore docs with override
+ page.languageCode === 'en' && // Only English pages enforce filename-title matching.
+ !page.relativePath.includes('index.md') && // TOCs do not use slugified filenames.
+ // Page has dynamic frontmatter properties that its type omits.
+ !(page as Record<string, unknown>).allowTitleToDifferFromFilename && // Allows override.
slugger.slug(decode(page.title)) !== path.basename(page.relativePath, '.md') &&
slugger.slug(decode(page.shortTitle || '')) !== path.basename(page.relativePath, '.md')
)
})
- // make the output easier to read
+ // Format failures for review.
.map((page) => {
return JSON.stringify(
{
@@ -126,7 +126,7 @@ describe('pages module', () => {
test('every page has valid frontmatter', async () => {
const frontmatterErrors = chain(pages)
- // Page class has dynamic error properties like 'frontmatterErrors' not in type definition
+ // Loaded pages cannot expose frontmatterErrors because Page throws before construction.
.map((page) => (page as Record<string, unknown>).frontmatterErrors)
.filter(Boolean)
.flatten()
@@ -146,7 +146,7 @@ describe('pages module', () => {
const liquidErrors: Array<{ filename: string; error: string }> = []
for (const page of pages) {
- // Page class has dynamic properties like 'raw' markdown not in type definition
+ // raw is not a Page property here, so this loop does not parse page markdown.
const markdown = (page as Record<string, unknown>).raw as string
if (!patterns.hasLiquid.test(markdown)) continue
try {
diff --git a/src/frame/tests/path-utils.ts b/src/frame/tests/path-utils.ts
index 1df7e18f0bba..302b6ec4165e 100644
--- a/src/frame/tests/path-utils.ts
+++ b/src/frame/tests/path-utils.ts
@@ -31,7 +31,7 @@ describe('getProductStringFromPath', () => {
})
test('extracts product from versioned paths', () => {
- // Note: These tests use free-pro-team which is a supported version
+ // free-pro-team@latest is a supported version for these paths.
expect(getProductStringFromPath('/en/free-pro-team@latest/admin/installation')).toBe('admin')
expect(getProductStringFromPath('/free-pro-team@latest/actions/quickstart')).toBe('actions')
expect(getProductStringFromPath('/en/free-pro-team@latest/github/getting-started')).toBe(
@@ -40,7 +40,7 @@ describe('getProductStringFromPath', () => {
})
test('handles enterprise landing pages (version without product)', () => {
- // When a version is present but no product segment follows, return the version string
+ // A version without a product segment resolves to the version string.
expect(getProductStringFromPath('/en/free-pro-team@latest')).toBe('free-pro-team@latest')
expect(getProductStringFromPath('/enterprise-server@latest')).toBe('enterprise-server@latest')
})
diff --git a/src/frame/tests/permalink.ts b/src/frame/tests/permalink.ts
index a1b9e99426de..0f61f784590f 100644
--- a/src/frame/tests/permalink.ts
+++ b/src/frame/tests/permalink.ts
@@ -5,8 +5,7 @@ import enterpriseServerReleases from '@/versions/lib/enterprise-server-releases'
import nonEnterpriseDefaultVersion from '@/versions/lib/non-enterprise-default-version'
import getApplicableVersions from '@/versions/lib/get-applicable-versions'
-// Permalink constructor requires: languageCode, pageVersion, relativePath, title
-// Permalink.derive requires: languageCode, relativePath, title, versions (<- FM prop)
+// Permalink.derive receives applicableVersions after Page merges feature-derived versions.
describe('Permalink class', () => {
test('derives info for unversioned homepage', () => {
diff --git a/src/frame/tests/resolve-carousels.test.ts b/src/frame/tests/resolve-carousels.test.ts
index d185c24c10b6..a7a49d80f1c8 100644
--- a/src/frame/tests/resolve-carousels.test.ts
+++ b/src/frame/tests/resolve-carousels.test.ts
@@ -10,7 +10,7 @@ vi.mock('@/frame/lib/find-page', () => ({
vi.mock('@/content-render/index', () => ({
renderContent: vi.fn((content, _context, options) => {
- // When textOnly is true, return plain text (no HTML wrapper)
+ // textOnly returns plain text so carousel intros stay text-only.
if (options?.textOnly) {
return content
}
@@ -199,7 +199,6 @@ describe('resolveCarousels middleware', () => {
req.context!.pages,
req.context!.redirects,
)
- // Carousel should not be added if all articles are not found
expect(
(req.context!.page as Page & { carousels?: Record<string, ResolvedArticle[]> }).carousels,
).toBeUndefined()
@@ -217,7 +216,6 @@ describe('resolveCarousels middleware', () => {
await resolveCarousels(req, mockRes, mockNext)
- // Should still call next even on error
expect(mockNext).toHaveBeenCalled()
})
@@ -260,7 +258,7 @@ describe('resolveCarousels middleware', () => {
applicableVersions: ['free-pro-team@latest'],
}
- // Mock findPage to fail on first call (content-relative) and succeed on second (page-relative)
+ // First lookup is content-relative; second lookup is page-relative.
mockFindPage.mockReturnValueOnce(undefined).mockReturnValueOnce(testPage as unknown as Page)
const req = createMockRequest({
@@ -318,7 +316,6 @@ describe('resolveCarousels middleware', () => {
req.context!.redirects,
)
- // Verify that the href is a clean path without language/version
expect(
(req.context!.page as Page & { carousels?: Record<string, ResolvedArticle[]> }).carousels,
).toEqual({
@@ -354,7 +351,6 @@ describe('resolveCarousels middleware', () => {
await resolveCarousels(req, mockRes, mockNext)
- // The carousels should not be added since the article isn't available in enterprise-cloud
expect(
(req.context!.page as Page & { carousels?: Record<string, ResolvedArticle[]> }).carousels,
).toBeUndefined()
@@ -377,7 +373,6 @@ describe('resolveCarousels middleware', () => {
await resolveCarousels(req, mockRes, mockNext)
- // Should only have one article, not three duplicates
expect(
(req.context!.page as Page & { carousels?: Record<string, ResolvedArticle[]> }).carousels,
).toEqual({
diff --git a/src/frame/tests/secure-files.ts b/src/frame/tests/secure-files.ts
index 9c760ecd3bc6..bf795fab65f2 100644
--- a/src/frame/tests/secure-files.ts
+++ b/src/frame/tests/secure-files.ts
@@ -2,13 +2,7 @@ import fs from 'fs/promises'
import { describe, expect, test } from 'vitest'
-/*
- * Verify that a list of file paths are present and optionally have a CODEOWNERS entry
- *
- * name: Readable description of file(s)
- * path: Path to secure files (must match entry in CODEOWNERS if code owner required)
- * requiredCodeOwner: (optional) Name of code owner if a code owner is required
- */
+// path must match the CODEOWNERS entry when requiredCodeOwner is set.
type SecureFile = {
name: string
path: string
diff --git a/src/frame/tests/server.ts b/src/frame/tests/server.ts
index f97554d740ca..011911e5c17a 100644
--- a/src/frame/tests/server.ts
+++ b/src/frame/tests/server.ts
@@ -15,10 +15,8 @@ interface Category {
published_articles: string[]
}
-// Parses a Content-Security-Policy header into its directives. Mirrors the
-// behavior of the unmaintained `csp-parse` package it replaces: the policy is
-// lowercased, split on `;`, and each directive's values are returned as a
-// space-joined string, or an empty string when the directive is absent.
+// Match unmaintained csp-parse: lowercase the policy, split directives on semicolons, and join
+// each directive's values with spaces. get() returns '' when a directive is absent.
function parseCsp(policy: string) {
const directives = new Map<string, string>()
for (const part of (policy || '').toLowerCase().split(';')) {
@@ -33,10 +31,8 @@ function parseCsp(policy: string) {
describe('server', () => {
vi.setConfig({ testTimeout: 60 * 1000 })
+ // Warm /en first so a slow first page load fails here instead of in the first test.
beforeAll(async () => {
- // The first page load takes a long time so let's get it out of the way in
- // advance to call out that problem specifically rather than misleadingly
- // attributing it to the first test
const res = await get('/en')
expect(res.statusCode).toBe(200)
})
@@ -46,9 +42,7 @@ describe('server', () => {
expect(res.statusCode).toBe(200)
expect(res.headers['content-length']).toBe('0')
expect(res.body).toBe('')
- // Because the HEAD requests can't be different no matter what's
- // in the request headers (Accept-Language or Cookies)
- // it's safe to let it cache. The only key is the URL.
+ // HEAD responses ignore Accept-Language and Cookies, so URL alone can key the public cache.
expect(res.headers['cache-control']).toContain('public')
expect(res.headers['cache-control']).toMatch(/max-age=\d+/)
})
@@ -115,8 +109,7 @@ describe('server', () => {
expect(keys).toContain('product:get-started')
expect(keys).toContain('product:get-started,language:en')
expect(keys.some((key: string) => /^version:.+/.test(key))).toBe(true)
- // Exact key, not just a pattern, to lock the render side byte-for-byte to what
- // the purge job rebuilds from a changed file path (content/get-started/index.md).
+ // The render key must match the purge key derived from content/get-started/index.md.
expect(keys).toContain('language:en,path:get-started/index.md')
expect(keys).toContain(makePageSurrogateKey('en', 'get-started/index.md'))
expect(keys.length).toBeLessThanOrEqual(6)
@@ -129,8 +122,7 @@ describe('server', () => {
})
test('renders a 404 page', async () => {
- // Important to use the prefix /en/ on the failing URL or else
- // it will render a very basic plain text 404 response.
+ // The /en/ prefix reaches the full 404 page instead of the plain text fallback.
const $ = await getDOM('/en/not-a-real-page', { allow404: true })
expect(($ as unknown as { text(): string }).text()).toContain('Page not found.')
expect($.res.statusCode).toBe(404)
@@ -141,10 +133,7 @@ describe('server', () => {
expect(res.statusCode).toBe(404)
})
- // When using `got()` to send full end-to-end URLs, you can't use
- // URLs like in this test because got will
- // throw `RequestError: URI malformed`.
- // So for now, this test is skipped.
+ // The skip predates the native-fetch helper, which sends this malformed path unchanged.
test.skip('renders a 400 for invalid paths', async () => {
const $ = await getDOM('/en/%7B%')
expect($.res.statusCode).toBe(400)
@@ -153,7 +142,7 @@ describe('server', () => {
test('renders a 500 page when errors are thrown', async () => {
const $ = await getDOM('/_500', { allow500s: true })
expect($('h1').first().text()).toBe('Ooops!')
- // Using type assertion because cheerio v1 types don't include text() on root
+ // Cheerio v1 root types omit text().
expect(
($ as unknown as { text(): string }).text().includes('It looks like something went wrong.'),
).toBe(true)
@@ -177,7 +166,6 @@ describe('server', () => {
expect(res.statusCode).toBe(400)
})
- // see issue 9678
test('does not use cached intros in subcategories', async () => {
let $ = await getDOM(
'/en/get-started/importing-your-projects-to-github/importing-source-code-to-github/importing-a-git-repository-using-the-command-line',
@@ -196,7 +184,7 @@ describe('server', () => {
expect(res.headers['access-control-allow-origin']).toBe('*')
- // Check that it can be cached at the CDN
+ // CDN caching must not set cookies.
expect(res.headers['set-cookie']).toBeUndefined()
expect(res.headers['cache-control']).toContain('public')
expect(res.headers['cache-control']).toMatch(/max-age=[1-9]/)
@@ -213,11 +201,7 @@ describe('server', () => {
describeViaActionsOnly('Early Access articles', () => {
test('have noindex meta tags', async () => {
const allPages = await loadPages()
- // This is what the earlyAccessContext middleware does to get a
- // list of early-access pages for that TOC it displays when
- // viewing /en/early-access in development.
- // Here we're using it to get a least 1 page we can end-to-end
- // test to look at it's meta tags.
+ // Match earlyAccessContext's development TOC input: English hidden early-access articles.
const hiddenPages = allPages.filter(
(page) =>
page.languageCode === 'en' &&
@@ -237,7 +221,7 @@ describe('server', () => {
const res = await get('/articles/deleting-a-team', { followRedirects: false })
expect(res.statusCode).toBe(302)
expect(res.headers['set-cookie']).toBeUndefined()
- // language specific caching
+ // Language-specific redirects must vary by language headers.
expect(res.headers['cache-control']).toContain('public')
expect(res.headers['cache-control']).toMatch(/max-age=[1-9]/)
expect(res.headers.vary).toContain('accept-language')
@@ -249,18 +233,14 @@ describe('server', () => {
expect(res.statusCode).toBe(302)
expect(res.headers.location).toBe('/en')
expect(res.headers['set-cookie']).toBeUndefined()
- // language specific caching
+ // Language-specific redirects must vary by language headers.
expect(res.headers['cache-control']).toContain('public')
expect(res.headers['cache-control']).toMatch(/max-age=[1-9]/)
expect(res.headers.vary).toContain('accept-language')
expect(res.headers.vary).toContain('x-user-language')
})
- // This test exists because in a previous life, our NextJS used to
- // 500 if the 'Accept-Language' header was malformed.
- // We *used* have a custom middleware to cope with this and force a
- // fallback redirect.
- // See internal issue 19909
+ // Invalid Accept-Language once triggered a downstream Next.js 500; this route must redirect.
test('redirects /en if Accept-Language header is malformed', async () => {
const res = await get('/', {
headers: {
@@ -272,7 +252,7 @@ describe('server', () => {
expect(res.statusCode).toBe(302)
expect(res.headers.location).toBe('/en')
expect(res.headers['set-cookie']).toBeUndefined()
- // language specific caching
+ // Language-specific redirects must vary by language headers.
expect(res.headers['cache-control']).toContain('public')
expect(res.headers['cache-control']).toMatch(/max-age=[1-9]/)
expect(res.headers.vary).toContain('accept-language')
@@ -290,7 +270,7 @@ describe('server', () => {
expect(res.statusCode).toBe(302)
expect(res.headers.location).toBe('/en')
expect(res.headers['set-cookie']).toBeUndefined()
- // language specific caching
+ // Language-specific redirects must vary by language headers.
expect(res.headers['cache-control']).toContain('public')
expect(res.headers['cache-control']).toMatch(/max-age=[1-9]/)
expect(res.headers.vary).toContain('accept-language')
@@ -302,7 +282,7 @@ describe('server', () => {
expect(res.statusCode).toBe(302)
expect(res.headers.location.startsWith('/en/')).toBe(true)
expect(res.headers['set-cookie']).toBeUndefined()
- // language specific caching
+ // Language-specific redirects must vary by language headers.
expect(res.headers['cache-control']).toContain('public')
expect(res.headers['cache-control']).toMatch(/max-age=[1-9]/)
expect(res.headers.vary).toContain('accept-language')
@@ -359,7 +339,6 @@ describe('server', () => {
expect(res.statusCode).toBe(200)
expect(res.headers['content-type']).toContain('text/markdown')
expect(res.body).toMatch(/^# .+/)
- // Verify the landing page has content beyond just the title
expect(res.body).toMatch(/\n\n/)
expect(res.body.split('\n').length).toBeGreaterThan(3)
})
@@ -398,10 +377,9 @@ describe('static routes', () => {
expect(res.statusCode).toBe(200)
expect(res.headers['cache-control']).toContain('public')
expect(res.headers['cache-control']).toMatch(/max-age=\d+/)
- // Because static assets shouldn't be setting a cookie.
+ // Static assets must not set cookies.
expect(res.headers['set-cookie']).toBeUndefined()
- // The "Surrogate-Key" header is set so we can do smart invalidation
- // in the Fastly CDN. This needs to be available for static assets too.
+ // Unhashed asset URLs use the generic language surrogate key, not the manual key.
expect(res.headers['surrogate-key']).toBeTruthy()
expect(res.headers.etag).toBeUndefined()
expect(res.headers['last-modified']).toBeTruthy()
@@ -433,7 +411,7 @@ describe('static routes', () => {
expect(res.statusCode).toBe(200)
expect(res.headers['cache-control']).toContain('public')
expect(res.headers['cache-control']).toMatch(/max-age=\d+/)
- // Because static assets shouldn't be setting a cookie.
+ // Static assets must not set cookies.
expect(res.headers['set-cookie']).toBeUndefined()
expect(res.headers.etag).toBeUndefined()
expect(res.headers['last-modified']).toBeTruthy()
@@ -459,8 +437,7 @@ describe('static routes', () => {
'/server.js',
'/.git',
'/.env',
- // Also add paths that aren't at the root. But it doesn't matter
- // which page this is done for so much.
+ // Nested dotfile paths prove product routing cannot expose repo contents.
'/en/billing/.env',
'/en/billing/.env.local',
'/en/pages/.env_sample',
diff --git a/src/frame/tests/site-tree.ts b/src/frame/tests/site-tree.ts
index a62099e603be..1be82f9da431 100644
--- a/src/frame/tests/site-tree.ts
+++ b/src/frame/tests/site-tree.ts
@@ -37,14 +37,12 @@ describe('siteTree', () => {
const ghesLatest = `enterprise-server@${latestEnterpriseRelease}`
const ghesSiteTree = siteTree.en[ghesLatest]
- // Find a page in the tree that we know contains Liquid
const pageWithDynamicTitle = findPageInSiteTree(
ghesSiteTree,
siteTree.en[nonEnterpriseDefaultVersion],
`/en/${ghesLatest}/admin/installing-your-enterprise-server`,
)
- // Confirm the raw title contains Liquid
expect(pageWithDynamicTitle.page.title).toEqual(
'Installing {% data variables.product.prodname_enterprise %}',
)
@@ -62,7 +60,7 @@ describe('siteTree', () => {
function validate(currentPage: Tree): void {
const childPages: Tree[] = currentPage.childPages || []
for (const childPage of childPages) {
- // Store page reference before validation to avoid type narrowing
+ // Store page reference before validation to avoid type narrowing.
const pageRef: Tree = childPage
const isValid = siteTreeValidate(childPage)
let errors: string | undefined
diff --git a/src/frame/tests/url-encoding.ts b/src/frame/tests/url-encoding.ts
index 2c4d0e8d32c9..6927f46ff21c 100644
--- a/src/frame/tests/url-encoding.ts
+++ b/src/frame/tests/url-encoding.ts
@@ -2,15 +2,12 @@ import { describe, expect, test } from 'vitest'
import { get } from '@/tests/helpers/e2etest'
describe('URL encoding for version paths', () => {
+ // SharePoint encodes @ as %40: /en/enterprise-cloud@latest becomes /en/enterprise-cloud%40latest.
test('handles URL-encoded @ symbol in enterprise-cloud version', async () => {
- // SharePoint encodes @ as %40, so /en/enterprise-cloud@latest becomes /en/enterprise-cloud%40latest
const encodedUrl = '/en/enterprise-cloud%40latest/copilot/concepts/chat'
const res = await get(encodedUrl)
- // Should either:
- // 1. Work directly (200) - the encoded URL should decode and work
- // 2. Redirect (301/302) to the proper decoded URL
- // Should NOT return 404
+ // Encoded @ may render directly or redirect to the decoded URL, but it must not 404.
expect([200, 301, 302]).toContain(res.statusCode)
if (res.statusCode === 301 || res.statusCode === 302) {
@@ -48,21 +45,20 @@ describe('URL encoding for version paths', () => {
})
test('URL encoding in other parts of URL is preserved', async () => {
- // Only @ symbols in version paths should be decoded, other encoding should be preserved
+ // A literal @ in the version segment must not decode unrelated URL encoding.
const encodedUrl = '/en/enterprise-cloud@latest/copilot/concepts/some%20page'
const res = await get(encodedUrl)
- // This might 404 if the page doesn't exist, but shouldn't break due to encoding
+ // Missing pages may 404, but unrelated URL encoding must not break the request.
expect(res.statusCode).not.toBe(500)
})
test('Express URL properties are correctly updated after decoding', async () => {
- // Test that req.path, req.query, etc. are properly updated when req.url is modified
+ // Updating req.url must also refresh Express request properties such as req.path and req.query.
const encodedUrl = '/en/enterprise-cloud%40latest/copilot/concepts/chat?test=value'
const res = await get(encodedUrl)
- // Should work correctly (200 or redirect) - the middleware should properly update
- // req.path from '/en/enterprise-cloud%40latest/...' to '/en/enterprise-cloud@latest/...'
+ // Middleware updates req.path from enterprise-cloud%40latest to enterprise-cloud@latest.
expect([200, 301, 302]).toContain(res.statusCode)
})
})
diff --git a/src/ghes-releases/lib/parse-release-notes.ts b/src/ghes-releases/lib/parse-release-notes.ts
index e235430cd314..b27fe866693f 100644
--- a/src/ghes-releases/lib/parse-release-notes.ts
+++ b/src/ghes-releases/lib/parse-release-notes.ts
@@ -1,7 +1,5 @@
-/**
- * Pure parsing/extraction functions used by generate-release-notes.ts.
- * Extracted here so they can be unit-tested without triggering the CLI.
- */
+// generate-release-notes.ts uses side-effect-free parsers.
+// Tests can import them without starting the CLI.
import fs from 'fs'
import { load } from 'js-yaml'
@@ -11,14 +9,11 @@ export interface NoteEntry {
sourceUrl: string
}
-/**
- * Looks for ```yaml ... ``` blocks, or falls back to lines starting with "- heading:"
- */
+// Agent output can omit fences, so fall back to the first line starting with "- heading:".
export function extractYaml(agentOutput: string): string | null {
const fenced = agentOutput.match(/```ya?ml\s*\n([\s\S]*?)```/)
if (fenced) return fenced[1].trim()
- // Fall back: look for lines that look like YAML note entries
const lines = agentOutput.split('\n')
const yamlLines: string[] = []
let inYaml = false
@@ -27,7 +22,7 @@ export function extractYaml(agentOutput: string): string | null {
inYaml = true
}
if (inYaml) {
- // Stop if we hit a non-YAML line (not indented, not a list item, not a comment, not empty)
+ // End fallback YAML when the response resumes prose.
if (line.trim() && !line.match(/^[\s#-]/) && !line.match(/^\s+\w+:/)) {
break
}
@@ -66,17 +61,12 @@ export function parseNoteEntries(yamlStr: string, sourceUrl: string): NoteEntry[
}
}
} catch {
- // Malformed YAML returns no entries rather than throwing.
+ // Bad agent YAML produces no entries so one issue cannot stop the run.
}
return entries
}
-/**
- * Parse an existing release notes YAML file and extract NoteEntry[] from it,
- * along with a set of source issue URLs already covered.
- * Returns { entries, coveredUrls } or null if the file doesn't exist.
- */
export function loadExistingEntries(yamlPath: string): {
entries: NoteEntry[]
coveredUrls: Set<string>
@@ -87,16 +77,8 @@ export function loadExistingEntries(yamlPath: string): {
return loadExistingEntriesFromString(content)
}
-/**
- * Parse release notes YAML content (as a string) and extract NoteEntry[] from it.
- * This is the testable core, with no file I/O.
- *
- * Note: This uses manual line-by-line parsing instead of js-yaml because we need
- * to preserve the `# https://github.com/.../issues/NNN` source URL comments that
- * precede each note. YAML comments are stripped by `load()` and aren't part
- * of the YAML data model, so a standard parser can't track the comment-to-note
- * relationship we rely on for incremental mode and deduplication.
- */
+// Parse release notes YAML manually so source issue URL comments stay attached to notes.
+// js-yaml strips comments, which would break incremental mode and deduplication.
export function loadExistingEntriesFromString(content: string): {
entries: NoteEntry[]
coveredUrls: Set<string>
@@ -150,7 +132,7 @@ export function loadExistingEntriesFromString(content: string): {
if (currentSection === 'changes') currentHeading = 'Changes'
else if (currentSection === 'closing_down') currentHeading = 'Closing down'
else if (currentSection === 'retired') currentHeading = 'Retired'
- else currentHeading = null // known_issues: skip
+ else currentHeading = null // Known issues stay in the placeholder template.
continue
}
@@ -213,10 +195,6 @@ export function loadExistingEntriesFromString(content: string): {
return { entries, coveredUrls }
}
-/**
- * Append YAML lines for a list of note entries at a given indentation level.
- * Handles the `# sourceUrl`, `- |`, and multi-line note content pattern.
- */
export function appendNoteLines(lines: string[], noteEntries: NoteEntry[], indent: string): void {
for (const entry of noteEntries) {
lines.push(`${indent}# ${entry.sourceUrl}`)
@@ -263,7 +241,6 @@ export function buildReleaseNotesYaml(
lines.push('sections:')
- // Features (grouped by heading).
const featureEntries = noteEntries.filter((e) => featureHeadings.includes(e.heading))
const otherEntries = noteEntries.filter((e) => !featureHeadings.includes(e.heading))
@@ -291,7 +268,6 @@ export function buildReleaseNotesYaml(
lines.push(' # TODO: Add feature notes')
}
- // Changes.
const changeEntries = otherEntries.filter((e) => !['Closing down', 'Retired'].includes(e.heading))
if (changeEntries.length > 0) {
lines.push('')
@@ -299,14 +275,12 @@ export function buildReleaseNotesYaml(
appendNoteLines(lines, changeEntries, ' ')
}
- // Known issues.
lines.push('')
lines.push(' known_issues:')
lines.push(' # TODO: Add known issues from "GHES Release Note Tracking" project')
lines.push(' - |')
lines.push(' ...')
- // Closing down.
const closingEntries = otherEntries.filter((e) => e.heading === 'Closing down')
if (closingEntries.length > 0) {
lines.push('')
@@ -314,7 +288,6 @@ export function buildReleaseNotesYaml(
appendNoteLines(lines, closingEntries, ' ')
}
- // Retired.
const retiredEntries = otherEntries.filter((e) => e.heading === 'Retired')
if (retiredEntries.length > 0) {
lines.push('')
diff --git a/src/ghes-releases/lib/release-issues.ts b/src/ghes-releases/lib/release-issues.ts
index 91e0d89cb3bd..f56c37f01956 100644
--- a/src/ghes-releases/lib/release-issues.ts
+++ b/src/ghes-releases/lib/release-issues.ts
@@ -7,9 +7,6 @@ interface IssueLike {
labels: { name: string }[]
}
-/**
- * Parse and validate the issue state filter. Defaults to "all".
- */
export function parseIssueState(value?: string): IssueState {
if (!value) return 'all'
@@ -41,9 +38,7 @@ export function buildReleaseIssueListArgs(version: string, issueState: IssueStat
]
}
-/**
- * Excludes release issues that should not produce GHES release notes.
- */
+// "public roadmap" and "not planned" issues never produce GHES release notes.
export function isExcludedReleaseIssue(issue: IssueLike): boolean {
return issue.labels.some((l) => EXCLUDED_RELEASE_LABELS.has(l.name.toLowerCase()))
}
diff --git a/src/ghes-releases/scripts/create-enterprise-issue.ts b/src/ghes-releases/scripts/create-enterprise-issue.ts
index b19db2e4366c..2d3ef022f680 100644
--- a/src/ghes-releases/scripts/create-enterprise-issue.ts
+++ b/src/ghes-releases/scripts/create-enterprise-issue.ts
@@ -1,7 +1,8 @@
-/**
- * @purpose Writer tool
- * @description Create release tracking issues for a new GHES version
- */
+// @purpose Writer tool
+// @description Create release tracking issues for a new GHES version
+//
+// Creates release and deprecation issues in github/docs-content and github/technical-content.
+// Skips a release or deprecation when its issue already exists.
import { readFileSync } from 'fs'
import { basename } from 'path'
import { Liquid } from 'liquidjs'
@@ -45,25 +46,15 @@ interface IssueSearchOpts {
titleMatch?: string
}
-// Required by github() to authenticate
if (!process.env.GITHUB_TOKEN) {
throw new Error('Error! You must have a GITHUB_TOKEN set in an .env file to run this script.')
}
const octokit = github()
const liquid = new Liquid()
-// [start-readme]
-//
-// This script creates enterprise release and deprecation issues in the
-// github/docs-content and github/technical-content repositories.
-// The script checks if an issue already exists for the release or deprecation.
-//
-// [end-readme]
run()
async function run() {
- // This script requires one parameters with the value
- // of either 'release' or 'deprecation'
const releaseType = process.argv[2]
if (releaseType !== 'release' && releaseType !== 'deprecation') {
throw new Error(
@@ -82,7 +73,6 @@ async function run() {
async function createDeprecationIssue() {
const repo = 'github/technical-content'
console.log('Next deprecation number: ', oldestSupported)
- // If an issue already exists for this release, do nothing
const issueExists = await isExistingIssue(repo, {
titleMatch: `Enterprise Server ${oldestSupported} deprecation steps`,
labels: ['enterprise deprecation'],
@@ -124,7 +114,6 @@ async function createReleaseIssue() {
const releaseNumber = getNextReleaseNumber(releaseDates)
console.log('Next release number: ', releaseNumber)
- // If an issue already exists for this release, do nothing
if (
await isExistingIssue(repo, {
labels: ['ghes-release-automation', `GHES ${releaseNumber}`],
@@ -136,8 +125,6 @@ async function createReleaseIssue() {
const releaseInfo = releaseDates[releaseNumber]
const rcDate = releaseInfo.release_candidate
- // Only open an issue if today is within 30 days before
- // the release candidate date
if (getNumberDaysUntilMilestone(rcDate || '') > 30) {
console.log(
`The ${releaseNumber} release candidate is not until ${rcDate}! An issue will be opened 30 days prior to the release candidate date.`,
@@ -147,8 +134,7 @@ async function createReleaseIssue() {
const releaseTemplates = getReleaseTemplates()
- // Set shell issues with placeholder title and body
- // Need all issue numbers before filling in liquid templates
+ // Create placeholder issues first because Liquid templates need every issue URL.
for (const templateName of Object.keys(releaseTemplates)) {
const issue = await createIssue(
repo,
@@ -161,7 +147,6 @@ async function createReleaseIssue() {
releaseTemplates[templateName].issue = issue.data
}
- // Go back and update title and body with rendered liquid templates
const releaseTemplateContext = getReleaseTemplateContext(
releaseNumber,
releaseInfo,
@@ -201,7 +186,6 @@ async function createIssue(
throw error
}
if (issue.status === 201) {
- // Write the values to disk for use in the workflow.
console.log(
`Issue #${issue.data.number} for the ${releaseNumber} ${releaseType} was opened: ${issue.data.html_url}`,
)
@@ -305,15 +289,12 @@ function getReleaseTemplateContext(
'release-code-freeze-date': releaseInfo.code_freeze || '',
'release-rc-target-date': releaseInfo.release_candidate || '',
}
- // Add a context variable for each issue url
for (const [templateName, template] of Object.entries(releaseTemplates)) {
if (template.issue) {
context[`${templateName}-url`] = template.issue.html_url
}
}
- // Create a context variable for each of the
- // 7 days before release-rc-target-date
if (releaseInfo.release_candidate) {
const rcTargetDate = new Date(releaseInfo.release_candidate).getTime()
for (let i = 1; i <= 7; i++) {
@@ -356,10 +337,6 @@ function getNextReleaseNumber(releaseDates: ReleaseDates): string {
return Object.keys(releaseDates)[indexOfNext]
}
-// examples:
-// searchQuery: 'author:docs-bot is:open'
-// labels: ['enterprise deprecation', 'ghes 3.0']
-// titleMatch: 'GHES 3.0'
async function isExistingIssue(
repo: string,
opts: IssueSearchOpts = { labels: undefined, searchQuery: undefined, titleMatch: undefined },
diff --git a/src/ghes-releases/scripts/deprecate/archive-version.ts b/src/ghes-releases/scripts/deprecate/archive-version.ts
index 9c1f807ba498..46b0a8183f18 100755
--- a/src/ghes-releases/scripts/deprecate/archive-version.ts
+++ b/src/ghes-releases/scripts/deprecate/archive-version.ts
@@ -1,10 +1,5 @@
-// [start-readme]
-//
-// Run this script during the Enterprise deprecation process to download
-// static copies of all pages for the oldest supported Enterprise version.
-// See the Enterprise deprecation issue template for instructions.
-//
-// [end-readme]
+// Run during Enterprise deprecation to download static pages for the oldest supported version.
+// The Enterprise deprecation issue template owns the operational checklist.
import path from 'path'
import fs from 'fs'
@@ -90,7 +85,6 @@ async function main() {
}
}
- // remove temp directory
await fs.promises.rm(tmpArchivalDirectory, { recursive: true, force: true })
const app = createApp()
@@ -103,8 +97,7 @@ async function main() {
await scrape({
urls,
urlFilter: (url: string) => {
- // Do not download assets from other hosts like S3 or octodex.github.com
- // (this will keep them as remote references in the downloaded pages)
+ // Leave assets on other hosts as remote references in downloaded pages.
return url.startsWith(`http://localhost:${port}/`)
},
directory: tmpArchivalDirectory,
@@ -126,7 +119,7 @@ async function main() {
console.log(`\n\ndone scraping! added files to ${tmpArchivalDirectory}\n`)
if (!singlePage) {
- // create redirect html files to preserve frontmatter redirects
+ // Redirect files preserve frontmatter redirects after static scraping.
await createRedirectsFile(pageList, path.join(tmpArchivalDirectory, version))
console.log(`next step: deprecate ${version} in lib/enterprise-server-releases.ts`)
} else {
@@ -148,9 +141,9 @@ async function createRedirectsFile(pageList: PageList, outputDirectory: string)
const redirectEntries: Array<[string, string]> = Object.entries(redirects)
for (let [oldPath, newPath] of redirectEntries) {
- // remove any liquid variables that sneak in
+ // Redirect paths can include Liquid version variables.
oldPath = oldPath.replace('/{{ page.version }}', '').replace('/{{ currentVersion }}', '')
- // ignore any old paths that are not in this version
+ // Keep only redirects for the archived Enterprise version.
if (
!(
oldPath.includes(`/enterprise-server@${version}`) ||
diff --git a/src/ghes-releases/scripts/deprecate/collapse-blank-lines.ts b/src/ghes-releases/scripts/deprecate/collapse-blank-lines.ts
index 52815b0b91d8..29290bf4a2b4 100644
--- a/src/ghes-releases/scripts/deprecate/collapse-blank-lines.ts
+++ b/src/ghes-releases/scripts/deprecate/collapse-blank-lines.ts
@@ -1,13 +1,9 @@
import fs from 'fs'
import { execSync } from 'child_process'
-// Removing deprecated Liquid conditionals leaves behind extra blank lines.
-// The content team flags these every deprecation, and the MD012 linter rule
-// is off so nothing catches them automatically. This collapses any run of
-// two or more consecutive blank lines down to one, but only in the markdown
-// files the deprecation actually changed. Single blank lines are left alone:
-// removed Liquid can introduce one in a place where it doesn't belong, so a
-// human still reviews each removal site one at a time.
+// Deprecated Liquid conditionals leave extra blank lines that content reviewers flag.
+// MD012 does not catch them in this repo. Collapse runs of two or more blank lines only in
+// markdown files changed by deprecation. Single blank lines still need human review.
function getChangedMarkdownFiles(): string[] {
const commands = [
@@ -21,7 +17,7 @@ function getChangedMarkdownFiles(): string[] {
try {
output = execSync(command, { encoding: 'utf8' })
} catch {
- // origin/main may not be fetched locally; skip that source.
+ // Skip origin/main when it is not fetched locally.
continue
}
for (const line of output.split('\n')) {
@@ -35,7 +31,6 @@ function getChangedMarkdownFiles(): string[] {
return [...files].sort()
}
-// Collapses any run of 2+ blank lines into a single blank line.
function collapse(contents: string): string {
const lines = contents.split('\n')
const result: string[] = []
diff --git a/src/ghes-releases/scripts/deprecate/create-docs-ghes-version-repo.sh b/src/ghes-releases/scripts/deprecate/create-docs-ghes-version-repo.sh
index 76f7be8ef6d9..b357b9add60e 100755
--- a/src/ghes-releases/scripts/deprecate/create-docs-ghes-version-repo.sh
+++ b/src/ghes-releases/scripts/deprecate/create-docs-ghes-version-repo.sh
@@ -1,13 +1,11 @@
-# This script creates a new repository for an archived version of GitHub Enterprise Server documentation.
-# Please update the version variable first.
-# You may wish to run this script a little bit at a time instead of all at once incase there are any errors.
+# Creates a repository for an archived GitHub Enterprise Server documentation version.
+# Pass the version as the first argument, and run sections one at a time when inspecting failures.
version=$1
cd ~/Documents/gh/github
-# Teams are addressed by numeric ID because IDs survive team renames and slugs do not.
-# Some APIs (repo creation, CODEOWNERS, custom properties) only accept slugs, so
-# resolve the current slug from the ID at runtime rather than hardcoding it.
+# Numeric team IDs survive team renames; slugs do not.
+# Repo creation, CODEOWNERS, and custom properties require slugs, so resolve current slugs.
org_id=9919
docs_team_id=325922
docs_eng_team_id=3935808
diff --git a/src/ghes-releases/scripts/deprecate/rewrite-asset-paths.ts b/src/ghes-releases/scripts/deprecate/rewrite-asset-paths.ts
index 0ae4cc3cd8ad..a04414779db9 100644
--- a/src/ghes-releases/scripts/deprecate/rewrite-asset-paths.ts
+++ b/src/ghes-releases/scripts/deprecate/rewrite-asset-paths.ts
@@ -24,6 +24,7 @@ export class RewriteAssetPathsPlugin {
this.replaceUrl = replaceUrl
}
+ // HTML and CSS asset paths must point at the archive site unless local-dev leaves them relative.
apply(
registerAction: (event: string, callback: (args: ResourceSavedArgs) => Promise<void>) => void,
) {
@@ -35,12 +36,8 @@ export class RewriteAssetPathsPlugin {
const text = resource.getText()
let newBody = text
- // Rewrite HTML asset paths. Example:
- // ../assets/images/foo/bar.png ->
- // https://github.github.com/docs-ghes-3.10/assets/images/foo/bar.png
-
if (resource.isHtml()) {
- // Remove nextjs scripts and manifest.json link
+ // Next.js runtime files break static archives.
newBody = newBody.replace(
/<script\ssrc="(\.\.\/)*_next\/static\/[\w]+\/(_buildManifest|_ssgManifest).js?".*?><\/script>/g,
'',
@@ -58,11 +55,6 @@ export class RewriteAssetPathsPlugin {
}
}
- // Rewrite CSS asset paths. Example
- // url("../assets/fonts/alliance/alliance-no-1-regular.woff") ->
- // url("https://github.github.com/docs-ghes-3.10/assets/fonts/alliance/alliance-no-1-regular.woff")
- // url(../../../assets/cb-303/images/octicons/search-24.svg) ->
- // url(https://github.github.com/docs-ghes-3.10/assets/cb-303/images/octicons/search-24.svg)
if (resource.isCss()) {
if (!this.localDev) {
newBody = newBody.replace(
diff --git a/src/ghes-releases/scripts/deprecate/update-automated-pipelines.ts b/src/ghes-releases/scripts/deprecate/update-automated-pipelines.ts
index 46c1f1a0ae04..c237d016948c 100755
--- a/src/ghes-releases/scripts/deprecate/update-automated-pipelines.ts
+++ b/src/ghes-releases/scripts/deprecate/update-automated-pipelines.ts
@@ -1,13 +1,6 @@
-// [start-readme]
-//
-// This script adds and removes placeholder data files in the
-// automation pipelines data directories and
-// data/release-notes/enterprise-server directories. This script
-// uses the supported and deprecated versions to determine what
-// directories should exist. This script also modifies the `api-versions`
-// key if it exists in a pipeline's lib/config.json file.
-//
-// [end-readme]
+// Adds and removes placeholder data for automation pipelines and GHES release notes
+// from the supported and deprecated GHES versions.
+// Updates api-versions in each pipeline lib/config.json when that key exists.
import { existsSync, rmSync } from 'fs'
import { mkdir, readFile, readdir, writeFile, cp } from 'fs/promises'
@@ -20,8 +13,8 @@ const pipelines = JSON.parse(await readFile('src/automated-pipelines/lib/config.
'automation-pipelines'
]
-// If the config file for a pipeline includes `api-versions` update that list
-// based on the supported and deprecated releases.
+// Pipelines with api-versions copy previous calendar date variants to the current release.
+// Deprecated variants are dropped.
export async function updateAutomatedConfigFiles() {
for (const pipeline of pipelines) {
const configFilepath = `src/${pipeline}/lib/config.json`
@@ -29,12 +22,10 @@ export async function updateAutomatedConfigFiles() {
const apiVersions = configData['api-versions']
if (!apiVersions) continue
for (const key of Object.keys(apiVersions)) {
- // Copy the previous release's calendar date versions to the new release
if (key.endsWith(previousReleaseNumber)) {
const newKey = key.replace(previousReleaseNumber, currentReleaseNumber)
apiVersions[newKey] = apiVersions[key]
}
- // Remove any deprecated versions
for (const deprecatedRelease of deprecated) {
if (key.endsWith(deprecatedRelease)) {
delete apiVersions[key]
@@ -49,15 +40,9 @@ export async function updateAutomatedConfigFiles() {
}
export async function updateAutomatedPipelines() {
- // The allVersions object uses the 'api-versions' data stored in the
- // src/rest/lib/config.json file. We want to update 'api-versions'
- // before the allVersions object is created so we need to import it
- // after calling updateAutomatedConfigFiles.
+ // Import allVersions after config updates so src/rest/lib/config.json changes take effect.
const { allVersions } = await import('@/versions/lib/all-versions')
- // Gets all of the base names (e.g., ghes-) in the allVersions object
- // Currently, this is only ghes- but if we had more than one type of
- // numbered release it would get all of them.
const numberedReleaseBaseNames = Array.from(
new Set(
Object.values(allVersions)
@@ -66,12 +51,7 @@ export async function updateAutomatedPipelines() {
),
)
- // A list of currently supported versions (calendar date inclusive)
- // in the format using the short name rather than full format
- // (e.g., enterprise-server@). The list is filtered
- // to only include versions that have numbered releases (e.g. ghes-).
- // The list is generated from the `apiVersions` key in allVersions.
- // This is currently only needed for the rest and github-apps pipelines.
+ // rest and github-apps read calendar-date versions from allVersions.apiVersions.
const versionNamesCalDate = Object.values(allVersions)
.filter((version) => version.hasNumberedReleases)
.map((version) =>
@@ -80,16 +60,13 @@ export async function updateAutomatedPipelines() {
: version.openApiVersionName,
)
.flat()
- // A list of currently supported versions in the format using the short name
- // rather than the full format (e.g., enterprise-server@). The list is filtered
- // to only include versions that have numbered releases (e.g. ghes-).
- // Currently, this is used for the graphql and webhooks pipelines.
+ // graphql and webhooks read numbered versions in ghes-major.minor form.
const versionNames = Object.values(allVersions)
.filter((version) => version.hasNumberedReleases)
.map((version) => version.openApiVersionName)
for (const pipeline of pipelines) {
- // secret-scanning has a different directory structure than the others
+ // secret-scanning stores pattern docs outside the shared pipeline data layout.
const directoryWithReleases =
pipeline === 'secret-scanning'
? 'src/secret-scanning/data/pattern-docs'
@@ -101,8 +78,7 @@ export async function updateAutomatedPipelines() {
)['api-versions']
const directoryListing = await readdir(directoryWithReleases)
- // filter the directory list to only include directories that start with
- // basenames with numbered releases (e.g., ghes-).
+ // Limit pipeline data dirs to numbered release basenames like ghes-.
const existingDataDir = directoryListing.filter((directory) =>
numberedReleaseBaseNames.some((basename) => directory.startsWith(basename)),
)
@@ -113,19 +89,15 @@ export async function updateAutomatedPipelines() {
const expectedDirectory = isCalendarDateVersioned ? versionNamesCalDate : versionNames
- // Get a list of data directories to remove (deprecate) and remove them
- // This should only happen if a release is being deprecated.
const removeFiles = difference(existingDataDir, expectedDirectory)
for (const directory of removeFiles) {
console.log(`Removing src/${pipeline}/data/${directory}`)
rmSync(`src/${pipeline}/data/${directory}`, { recursive: true, force: true })
}
- // Get a list of data directories to create (release) and create them
- // This should only happen if a release is being added.
const addFiles = difference(expectedDirectory, existingDataDir)
- // Verify all new directories belong to the current release
+ // Reject directories unrelated to the current release before creating them.
for (const dir of addFiles) {
if (!dir.includes(currentReleaseNumber)) {
throw new Error(
@@ -136,15 +108,10 @@ export async function updateAutomatedPipelines() {
}
for (const base of numberedReleaseBaseNames) {
- // Find ALL directories to add for this base name (may be multiple
- // when a release has more than one calendar-date version).
+ // Calendar-date releases can add more than one directory for the same base name.
const dirsToAdd = addFiles.filter((item) => item.startsWith(base))
for (const dirToAdd of dirsToAdd) {
- // Derive the previous release's corresponding directory by replacing
- // the current release number with the previous one. This correctly
- // maps each calendar-date variant to its predecessor, e.g.:
- // ghes-3.20-2022-11-28 -> ghes-3.19-2022-11-28
- // ghes-3.20-2026-03-10 -> ghes-3.19-2026-03-10
+ // Keep calendar-date suffixes unchanged when mapping previous dirs to current dirs.
const previousDirName = dirToAdd.replace(currentReleaseNumber, previousReleaseNumber)
if (!existingDataDir.includes(previousDirName)) {
throw new Error(
@@ -163,9 +130,7 @@ export async function updateAutomatedPipelines() {
}
}
- // Add and remove the GHES release note data. Once we create an automation
- // pipeline for release notes, we can remove this because it will use the
- // same directory structure as the other pipeline data directories.
+ // GHES release notes stay in this path until an automation pipeline owns the same layout.
const ghesReleaseNotesDirs = await readdir('data/release-notes/enterprise-server')
const supportedHyphenated = supported.map((version) => version.replace('.', '-'))
const deprecatedHyphenated = deprecated.map((version) => version.replace('.', '-'))
diff --git a/src/ghes-releases/scripts/deprecate/update-content.ts b/src/ghes-releases/scripts/deprecate/update-content.ts
index 07422ed63dde..35004217f1a7 100644
--- a/src/ghes-releases/scripts/deprecate/update-content.ts
+++ b/src/ghes-releases/scripts/deprecate/update-content.ts
@@ -17,9 +17,8 @@ const contentFiles = walkFiles('content', {
ignore: ['**/README.md', '**/index.md'],
})
-// This module updates the versions frontmatter in content files.
-// When a content file contains only deprecated GHES releases, the
-// file is deleted and removed from the parent index.md file.
+// Updates versions frontmatter during GHES deprecation.
+// Deletes GHES-only files with no supported release from their parent index.md.
export function updateContentFiles() {
for (const file of contentFiles) {
const oldContents = fs.readFileSync(file, 'utf8')
@@ -35,16 +34,13 @@ export function updateContentFiles() {
throw new Error(`Could not load feature versions from ${featureFilePath}`)
}
- // skip files with no Enterprise Server versions frontmatter
if (!data.versions.ghes && !featureData?.versions?.ghes) continue
- // skip files with all ghes releases defined
if (data.versions.ghes === '*') continue
const deprecatedRelease = deprecated[0]
const oldestRelease = supported[supported.length - 1]
- // If the frontmatter versions.ghes property is now
- // applicable to all GHES releases, update the value to '*'.
+ // Feature-backed content becomes all versions when it applies to FPT, GHEC, and every GHES.
const featureAppliesToAllVersions =
featureData &&
featureData.versions.ghec &&
@@ -55,9 +51,7 @@ export function updateContentFiles() {
if (isInAllGhes(data.versions.ghes)) {
console.log('Updating GHES version in: ', file)
data.versions.ghes = '*'
- // To preserve newlines when stringifying,
- // you can set the lineWidth option to -1
- // This prevents updates to the file that aren't actual changes.
+ // lineWidth -1 preserves existing newlines, so only frontmatter changes are written.
fs.writeFileSync(
file,
frontmatter.stringify(content!, data, { lineWidth: -1 } as unknown as Parameters<
@@ -73,9 +67,7 @@ export function updateContentFiles() {
ghec: '*',
ghes: '*',
}
- // To preserve newlines when stringifying,
- // you can set the lineWidth option to -1
- // This prevents updates to the file that aren't actual changes.
+ // lineWidth -1 preserves existing newlines, so only frontmatter changes are written.
fs.writeFileSync(
file,
frontmatter.stringify(content!, data, { lineWidth: -1 } as unknown as Parameters<
@@ -87,9 +79,7 @@ export function updateContentFiles() {
const deprecatedRegex = new RegExp(`(<|<=)\\s?${deprecatedRelease}`, 'g')
const oldestRegex = new RegExp(`<\\s?${oldestRelease}`, 'g')
- // If the frontmatter versions.ghes property is now
- // deprecated, remove it. If the content file is only
- // versioned for GHES, remove the file and update index.md.
+ // Remove GHES frontmatter or delete GHES-only files when no supported GHES applies.
const featureGhes = featureData?.versions?.ghes || ''
const appliesToNoSupportedGhesReleases =
deprecatedRegex.test(data.versions.ghes) ||
@@ -101,7 +91,6 @@ export function updateContentFiles() {
if (Object.keys(data.versions).length === 1) {
removeFileUpdateParent(file)
} else {
- // Remove the ghes property from versions Fm and return
delete data.versions.ghes
console.log('Removing GHES version from: ', file)
fs.writeFileSync(
@@ -130,15 +119,14 @@ function removeFileUpdateParent(filePath: string) {
data: { children: string[] } | undefined
}
if (!data) return
- // Children paths are relative to the index.md file's directory
+ // Children paths are relative to the index.md file's directory.
const childPath = filePath.endsWith('index.md')
? `/${path.basename(path.dirname(filePath))}`
: `/${path.basename(filePath, '.md')}`
- // Remove the childPath from the parent index.md file's children frontmatter
data.children = data.children.filter((child) => child !== childPath)
- // If removing the childPath leaves the parent index.md file empty, remove it
+ // Empty parent indexes must disappear with their last child.
if (data.children.length === 0) {
removeFileUpdateParent(parentFilePath)
} else {
@@ -152,15 +140,10 @@ function removeFileUpdateParent(filePath: string) {
}
}
-// Gets the next parent file path.
-// If the filePath is an article (e.g., doesn't end with index.md),
-// then the parent file is the index.md file in the same directory.
-// If the filePath is a category or subcategory (e.g., ends with index.md),
-// the parent is the index.md file in the next directory up.
+// Articles use the index.md in their directory; index.md files use the parent directory's index.md.
+// content/index.md has no parent.
function getParentFilePath(filePath: string) {
- // This is the root index.md file, it has no parent
if (!filePath || filePath === 'content/index.md') return null
- // Handle index.md files with index.md parent in directory above
if (filePath.endsWith('index.md')) {
const pathParts = filePath.split('/')
pathParts.pop()
@@ -168,6 +151,5 @@ function getParentFilePath(filePath: string) {
pathParts.push('index.md')
return pathParts.join('/')
}
- // Handle articles with a parent index.md file
return filePath.replace(path.basename(filePath), 'index.md')
}
diff --git a/src/ghes-releases/scripts/deprecate/update-data.ts b/src/ghes-releases/scripts/deprecate/update-data.ts
index 08e91ce9e9b1..9b9badeff590 100644
--- a/src/ghes-releases/scripts/deprecate/update-data.ts
+++ b/src/ghes-releases/scripts/deprecate/update-data.ts
@@ -31,8 +31,7 @@ export function updateDataFiles() {
updateFeatureData()
}
-// Removes empty data/reusables files and removes the deleted
-// reusable from any content or data/reusables files that reference it.
+// Remove empty reusable files and their Liquid references so content does not use deleted data.
function updateReusableData() {
const deletedDataFiles = []
@@ -44,16 +43,12 @@ function updateReusableData() {
deletedDataFiles.push(file)
}
}
- // Map the format:
- // data/reusables/actions/actions-runner-controller-unsupported-customization.md
- // to the format:
- // {% data reusables.code-scanning.beta-org-enable-all %}
+ // Example: data/reusables/actions/runner.md becomes {% data reusables.actions.runner %}.
const reusableNames = deletedDataFiles.map(
(file) => `{% data ${file.replace('.md', '').split('/').slice(1).join('.')} %}`,
)
const existingDataReusables = difference(dataReusables, deletedDataFiles)
- // Remove deleted reusables from content and data resuables files
for (const file of [...existingDataReusables, ...contentFiles]) {
const originalContent = fs.readFileSync(file, 'utf8')
let content = originalContent
@@ -70,9 +65,7 @@ function updateReusableData() {
}
}
-// Removes deprecated data/feature files and outputs a list of data/features
-// available in all versions. That list is only used for review during a GHES
-// deprecation.
+// Lists all-version data/features for human review during GHES deprecation.
function updateFeatureData() {
const allFeatureFiles = new Set()
diff --git a/src/ghes-releases/scripts/generate-release-notes.ts b/src/ghes-releases/scripts/generate-release-notes.ts
index 1ecdd3ab3b21..9da6ed83aada 100644
--- a/src/ghes-releases/scripts/generate-release-notes.ts
+++ b/src/ghes-releases/scripts/generate-release-notes.ts
@@ -1,13 +1,8 @@
-/**
- * @purpose Writer tool
- * @description Generate GHES release notes from github/releases issues using Copilot CLI
- *
- * Generate GHES release notes by:
- * 1. Querying github/releases issues labeled "GHES <version>" (all states by default)
- * 2. Finding corresponding changelog PRs in github/blog
- * 3. Running each through the ghes-release-notes agent via Copilot CLI
- * 4. Stitching the YAML outputs into a release notes file
- */
+// @purpose Writer tool
+// @description Generate GHES release notes from github/releases issues using Copilot CLI
+//
+// Queries github/releases issues labeled with the GHES release number, all states by default.
+// Matches github/blog changelog PRs, runs ghes-release-notes, and writes release note YAML.
import { Command } from 'commander'
import { execFileSync, spawn, type ChildProcess } from 'child_process'
import fs from 'fs'
@@ -80,9 +75,7 @@ function loadFeatureHeadings(): string[] {
return _featureHeadingsCache
}
-/**
- * Run `gh` CLI commands with native auth (no GITHUB_TOKEN interference)
- */
+// Drop GITHUB_TOKEN so gh uses native auth instead of repo workflow auth.
function gh(args: string[]): string {
const env = { ...process.env }
delete env.GITHUB_TOKEN
@@ -105,11 +98,8 @@ interface ChangelogInfo {
body: string | null
}
-/**
- * Try to extract a changelog PR URL from a release issue body.
- * Looks for patterns like:
- * 📄 **Changelog post:** https://github.com/github/blog/pull/1234
- */
+// Release issues can link the changelog PR in a Changelog post field.
+// Example field: Changelog post. The value is a github/blog pull request URL.
function extractChangelogPrUrl(issueBody: string): string | null {
const match = issueBody.match(/https:\/\/github\.com\/github\/blog\/pull\/\d+/)
return match ? match[0] : null
@@ -125,11 +115,8 @@ function fetchChangelogPrBody(prUrl: string): string | null {
}
}
-/**
- * Search github/blog for a merged PR that references a release issue number.
- * Caches the fetched PR list to avoid redundant API calls.
- * Returns URL + body when found.
- */
+// Cache recent github/blog changelog PRs because multiple release issues search the same list.
+// Each changelog PR body links back to its release issue.
let _blogPrsCache: { number: number; body: string; url: string }[] | null = null
function searchChangelogPr(issueNumber: number): ChangelogInfo | null {
try {
@@ -170,10 +157,6 @@ function searchChangelogPr(issueNumber: number): ChangelogInfo | null {
return null
}
-/**
- * Find the changelog PR for a release issue, checking the issue body first,
- * then falling back to searching github/blog. Returns URL + body.
- */
function findChangelogPr(issue: ReleaseIssue): ChangelogInfo | null {
const fromBody = extractChangelogPrUrl(issue.body)
if (fromBody) {
@@ -183,11 +166,8 @@ function findChangelogPr(issue: ReleaseIssue): ChangelogInfo | null {
return searchChangelogPr(issue.number)
}
-/**
- * Resolve the Copilot CLI path.
- * Result is cached after first call.
- */
let _copilotCliPath: string | null = null
+// The VS Code extension fallback covers macOS only; otherwise which must find a global install.
function findCopilotCli(): string {
if (_copilotCliPath) return _copilotCliPath
@@ -199,10 +179,6 @@ function findCopilotCli(): string {
}
} catch {}
- // Fallback: check VS Code extension storage locations.
- // These paths are macOS-only. On Linux/Windows the `which` check above should
- // find Copilot CLI if it's installed globally. If needed, add platform-specific
- // paths here (e.g., ~/.config/Code/User/globalStorage/... for Linux).
const homeDir = os.homedir()
const vsCodePath = path.join(
homeDir,
@@ -225,11 +201,6 @@ function findCopilotCli(): string {
throw new Error('Copilot CLI not found. Install via: npm install -g @github/copilot@prerelease')
}
-/**
- * Run the ghes-release-notes agent on a release issue (+optional changelog PR)
- * via Copilot CLI and return the raw output.
- * Uses async spawn so SIGINT (Ctrl+C) is not blocked.
- */
interface AgentContext {
issueUrl: string
issueTitle: string
@@ -239,32 +210,27 @@ interface AgentContext {
featureHeadings: string[]
}
-/**
- * Extract the title tag (e.g., "GA", "Public Preview") from a release issue title.
- */
function parseTitleTag(title: string): string | null {
const match = title.match(/\[(GA|Public Preview|Beta|Private Preview|Closing Down|Retired)\]/i)
return match ? match[1] : null
}
+// Use async spawn so Ctrl+C can interrupt the agent process.
function runAgent(ctx: AgentContext): Promise<string> {
const copilotPath = findCopilotCli()
const titleTag = parseTitleTag(ctx.issueTitle)
- // Build an optimized prompt that pre-includes all context so the agent
- // doesn't need to make tool calls to fetch it.
+ // Preload context so the agent does not need network tools during note generation.
let prompt = `You are running in non-interactive mode. Do NOT ask any follow-up questions. `
prompt += `Generate a release note for ${ctx.issueUrl}. `
prompt += `Follow the ghes-release-notes agent instructions. `
prompt += `Return ONLY a single YAML code block (\`\`\`yaml ... \`\`\`). No conversation, no questions, no explanations outside the code block.\n\n`
- // Pre-supply the title tag so the agent doesn't need to re-parse
if (titleTag) {
prompt += `The issue title tag is [${titleTag}].\n\n`
}
- // Pre-supply valid headings so the agent doesn't need to read PLACEHOLDER-TEMPLATE.yml
prompt += `IMPORTANT: Do NOT read PLACEHOLDER-TEMPLATE.yml or data/variables/product.yml — all necessary context is provided below.\n\n`
prompt += `Valid feature headings (use ONLY these for feature notes):\n`
for (const h of ctx.featureHeadings) {
@@ -272,13 +238,11 @@ function runAgent(ctx: AgentContext): Promise<string> {
}
prompt += `\nFor non-feature notes, use: Changes, Closing down, or Retired.\n\n`
- // Pre-supply the issue body so the agent doesn't need to fetch it
prompt += `--- RELEASE ISSUE (${ctx.issueUrl}) ---\n`
prompt += `Title: ${ctx.issueTitle}\n`
prompt += ctx.issueBody.substring(0, 15000)
prompt += `\n--- END RELEASE ISSUE ---\n\n`
- // Pre-supply the changelog PR body if available
if (ctx.changelogUrl && ctx.changelogBody) {
prompt += `--- CHANGELOG PR (${ctx.changelogUrl}) ---\n`
prompt += ctx.changelogBody.substring(0, 10000)
@@ -379,14 +343,8 @@ interface AgentResult {
skipWarning?: string
}
-/**
- * Run the agent with retry logic. Retries up to `maxRetries` times on failure.
- * Validates that extracted YAML parses into non-empty entries before accepting.
- * If the agent tries to skip (returns `# SKIP: reason` + `[]`), treats it as a
- * failed attempt and retries, because issues that matched the GHES label filter should
- * always get a release note. If all attempts result in skips, the last skip
- * reason is attached as a warning.
- */
+// Retry agent failures and reject empty YAML so matching GHES issues produce release notes.
+// Skip signals become warnings only after every attempt skips.
async function runAgentWithRetry(ctx: AgentContext, maxRetries = 2): Promise<AgentResult> {
let lastError: Error | null = null
let lastRawOutput = ''
@@ -397,8 +355,7 @@ async function runAgentWithRetry(ctx: AgentContext, maxRetries = 2): Promise<Age
lastRawOutput = output
const yamlStr = extractYaml(output)
if (yamlStr) {
- // Detect agent skip signals and treat as retryable failures.
- // The issue already matched GHES labels, so we always want a release note.
+ // Treat skip signals as retryable because GHES-labeled issues need notes.
const skipReason =
extractSkipReason(yamlStr) ||
(Array.isArray(load(yamlStr)) && (load(yamlStr) as unknown[]).length === 0
@@ -418,7 +375,7 @@ async function runAgentWithRetry(ctx: AgentContext, maxRetries = 2): Promise<Age
skipWarning: lastSkipReason ?? undefined,
}
}
- // YAML was extracted but is empty or unparseable, so retry.
+ // Retry empty or unparseable YAML.
lastError = new Error(
`Agent returned YAML but it contained no valid entries (got: ${yamlStr.substring(0, 80)})`,
)
@@ -447,7 +404,7 @@ program
)
.requiredOption('-r, --release <version>', 'GHES release number (e.g., 3.20, 3.21)')
.option('--rc [boolean]', 'Generate release candidate notes (omit for GA)', (val: string) => {
- // Support both `--rc` (no value → true) and `--rc true`/`--rc false` (legacy)
+ // Accept --rc alone, --rc true, and --rc false.
if (val === undefined || val === 'true') return true
if (val === 'false') return false
return true
@@ -462,7 +419,7 @@ program
'-i, --issue <value>',
'Process a single issue by number or URL (replaces its entry if it already exists)',
(val: string) => {
- // Accept a full URL like https://github.com/github/releases/issues/6768
+ // Accept full github/releases issue URLs as well as numbers.
const urlMatch = val.match(/\/issues\/(\d+)/)
if (urlMatch) return parseInt(urlMatch[1], 10)
const num = parseInt(val, 10)
@@ -496,7 +453,6 @@ program
process.exit(1)
}
- // Prerequisite checks.
try {
execFileSync('gh', ['--version'], { stdio: 'ignore' })
} catch {
@@ -524,7 +480,6 @@ program
process.exit(1)
}
- // Step 1: Fetch release issues.
let issues: ReleaseIssue[]
if (singleIssue) {
@@ -570,12 +525,11 @@ program
process.exit(0)
}
- // GA meta-issues (e.g. "GHES 3.20 GA [GA]") are tracking issues, not features.
+ // GA meta-issues named GHES X.Y GA or GHES X.Y release are tracking issues.
const originalCount = issues.length
issues = issues.filter((issue) => {
const title = issue.title.trim()
const stripped = title.replace(/\s*\[[^\]]*\]/g, '').trim()
- // Skip issues whose title is just "GHES X.Y GA" or "GHES X.Y release"
if (/^ghes\s+\d+\.\d+\s+ga$/i.test(stripped)) return false
if (/^ghes\s+\d+\.\d+\s+release$/i.test(stripped)) return false
return true
@@ -613,14 +567,14 @@ program
const outputDir = path.join(process.cwd(), 'data/release-notes/enterprise-server', dirName)
const outputPath = path.join(outputDir, fileName)
- // Incremental mode: load existing entries.
+ // Existing entries make generation incremental by default.
const allEntries: NoteEntry[] = []
let existingCoveredUrls = new Set<string>()
if (!force && !stdout && fs.existsSync(outputPath)) {
const existing = loadExistingEntries(outputPath)
if (existing && existing.entries.length > 0) {
- // When --issue is specified, remove the old entry for that issue so it gets regenerated
+ // Regenerate a single issue by dropping its previous source URL entry first.
if (singleIssue) {
const issueUrl = `https://github.com/github/releases/issues/${singleIssue}`
const kept = existing.entries.filter((e) => e.sourceUrl !== issueUrl)
@@ -638,7 +592,7 @@ program
}
}
- // Filter out issues already covered by existing file (incremental mode)
+ // Incremental mode skips release issues already covered by the existing file.
if (existingCoveredUrls.size > 0 && !singleIssue) {
const beforeCount = issues.length
issues = issues.filter((issue) => !existingCoveredUrls.has(issue.url))
@@ -652,7 +606,6 @@ program
}
}
- // Step 2: Find changelog PRs.
spinner.start('Finding changelog PRs...')
const issueChangelogMap = new Map<number, ChangelogInfo | null>()
let changelogFound = 0
@@ -664,14 +617,12 @@ program
}
spinner.succeed(`Found changelog PRs for ${changelogFound}/${issues.length} issues`)
- // Step 3: Run agent on each issue.
const failures: { issue: ReleaseIssue; error: string }[] = []
const existingEntryCount = allEntries.length
- // Hoisted for clarity. The underlying load is already cached.
const featureHeadings = loadFeatureHeadings()
- // Helper to write current entries to file (called after each success and on Ctrl+C)
+ // Flush after each success and on Ctrl+C so long runs keep completed notes.
const writeCurrentOutput = () => {
if (stdout || allEntries.length === 0) return
try {
@@ -712,15 +663,14 @@ program
)
}
- // entries are pre-validated by runAgentWithRetry, but re-parse for the actual list
+ // Re-parse validated YAML so the main list uses parseNoteEntries output.
const entries = parseNoteEntries(result.yamlStr, issue.url)
- // Warn about headings that don't match any known feature heading or special section
+ // Unknown headings fall back to changes after case-insensitive correction fails.
const specialHeadings = ['Changes', 'Closing down', 'Retired']
const validHeadings = new Set([...featureHeadings, ...specialHeadings])
for (const entry of entries) {
if (!validHeadings.has(entry.heading)) {
- // Check for near-matches (case-insensitive)
const lowerHeading = entry.heading.toLowerCase()
const closeMatch = featureHeadings.find((h) => h.toLowerCase() === lowerHeading)
if (closeMatch) {
@@ -734,7 +684,7 @@ program
}
}
- // Dedup: avoid duplicate notes if the same issue was partially loaded from an existing file
+ // Avoid duplicates when an existing file already contributed the same issue note.
for (const entry of entries) {
const isDuplicate = allEntries.some(
(existing) =>
@@ -765,7 +715,7 @@ program
console.log(` Reason: ${skipReason}`)
} else {
spinner.fail(`${label} — ${msg.substring(0, 100)}`)
- // Show raw agent output only for real errors
+ // Show raw agent output only for real errors.
if (err.rawOutput) {
console.log('\n --- Raw agent output (last attempt) ---')
const truncated =
@@ -779,7 +729,6 @@ program
}
}
- // Step 4: Final summary.
flushBeforeExit = null
const newCount = allEntries.length - existingEntryCount
if (existingEntryCount > 0) {
@@ -802,7 +751,7 @@ program
process.exit(1)
}
if (singleIssue) {
- // For a single issue + stdout, print just the raw note YAML (not the full template)
+ // Single-issue stdout prints note entries, not the full release template.
const newEntries = allEntries.filter(
(e) => e.sourceUrl === `https://github.com/github/releases/issues/${singleIssue}`,
)
@@ -828,7 +777,7 @@ program
console.log('\nNo entries generated — no file written.')
}
- // Clean up stdin raw mode so the process can exit gracefully
+ // Clean up stdin raw mode so the process can exit gracefully.
if (process.stdin.isTTY) {
process.stdin.setRawMode(false)
process.stdin.pause()
diff --git a/src/ghes-releases/scripts/notify-release-pms.ts b/src/ghes-releases/scripts/notify-release-pms.ts
index 79adb25aad38..fb12bd9791ad 100644
--- a/src/ghes-releases/scripts/notify-release-pms.ts
+++ b/src/ghes-releases/scripts/notify-release-pms.ts
@@ -1,21 +1,10 @@
-/**
- * @purpose Writer tool
- * @description Notify PMs to review their GHES release notes on a PR
- *
- * Notify PMs about generated GHES release notes by posting a review comment
- * on each source release issue in github/releases.
- *
- * For each release issue URL found in the YAML file's `# https://...` comments,
- * this script posts a comment asking the PM to review the note in the PR and
- * react with 🚀 once satisfied.
- *
- * Usage:
- * # Post comments via GitHub Actions (handles auth automatically):
- * gh workflow run notify-release-pms.yml -f release=3.20 -f pr=12345
- *
- * # Preview locally (dry run, no token needed):
- * npm run notify-release-pms -- --release 3.20 --pr 12345 --dry-run
- */
+// @purpose Writer tool
+// @description Notify PMs to review their GHES release notes on a PR
+//
+// Posts docs-bot review comments on github/releases source issues from YAML source comments.
+// Product managers (PMs) review the PR and react with 🚀 when satisfied.
+// GitHub Actions usage: gh workflow run notify-release-pms.yml -f release=<release> -f pr=<pr>
+// Local preview: npm run notify-release-pms -- --release <release> --pr <pr> --dry-run
import { Command } from 'commander'
import { execFileSync } from 'child_process'
import fs from 'fs'
@@ -27,11 +16,7 @@ export interface SourceNote {
issueNumber: number
}
-/**
- * Run read-only `gh` CLI commands.
- * Uses DOCS_BOT_PAT_BASE when available (CI), otherwise falls back to
- * the caller's native `gh` auth (local).
- */
+// DOCS_BOT_PAT_BASE authenticates CI reads; caller gh auth handles local reads.
function ghRead(args: string[]): string {
const env = { ...process.env }
if (env.DOCS_BOT_PAT_BASE) {
@@ -46,10 +31,7 @@ function ghRead(args: string[]): string {
})
}
-/**
- * Run `gh` CLI commands authenticated as docs-bot (for posting comments).
- * Requires the DOCS_BOT_PAT_BASE environment variable to be set.
- */
+// Posting comments requires DOCS_BOT_PAT_BASE so they come from docs-bot.
function ghWrite(args: string[]): string {
const token = process.env.DOCS_BOT_PAT_BASE
if (!token) {
@@ -62,7 +44,7 @@ function ghWrite(args: string[]): string {
process.exit(1)
}
const env = { ...process.env, GH_TOKEN: token }
- // Ensure GH_TOKEN takes precedence over any pre-existing GITHUB_TOKEN
+ // GH_TOKEN must take precedence over any pre-existing GITHUB_TOKEN.
delete (env as Record<string, string | undefined>).GITHUB_TOKEN
return execFileSync('gh', args, {
encoding: 'utf8',
@@ -72,11 +54,7 @@ function ghWrite(args: string[]): string {
})
}
-/**
- * Parse release notes content and extract source issue URLs.
- * Each `# https://github.com/github/releases/issues/NNNN` comment
- * maps to the note(s) that follow it.
- */
+// Source issue URL comments attach each generated note to its github/releases issue.
export function parseSourceNotes(content: string): SourceNote[] {
const lines = content.split('\n')
const notes: SourceNote[] = []
@@ -86,8 +64,7 @@ export function parseSourceNotes(content: string): SourceNote[] {
const match = lines[i].match(/^\s*#\s*(https:\/\/github\.com\/github\/releases\/issues\/(\d+))/)
if (match) {
const issueNumber = parseInt(match[2], 10)
- // Some issues appear multiple times (e.g. in features and changes). Keep the
- // first occurrence so the link points to the primary note.
+ // Keep the first occurrence so duplicate issue links point to the primary note.
if (!seen.has(issueNumber)) {
seen.add(issueNumber)
notes.push({
@@ -116,8 +93,7 @@ export function buildCommentBody(
const prUrl = `https://github.com/github/docs-internal/pull/${prNumber}`
const fileUrl = `${prUrl}/files`
- // Use a marker so we can identify our comments later (for duplicate-prevention).
- // Include releaseType so RC and GA comments are distinguishable.
+ // Mark comments for duplicate detection; releaseType keeps RC and GA distinct.
const marker = buildMarker(version, releaseType.toLowerCase() as 'rc' | 'ga')
const mentions = assignees.length > 0 ? `${assignees.map((a) => `@${a}`).join(' ')} ` : ''
@@ -222,7 +198,7 @@ program
process.exit(1)
}
} else {
- // Auto-detect: prefer GA if it exists, otherwise RC (consistent with generate-release-notes)
+ // Auto-detect prefers GA over RC to match generate-release-notes.
if (fs.existsSync(gaPath)) {
rc = false
yamlPath = gaPath
@@ -239,7 +215,6 @@ program
const relativeFilePath = path.relative(process.cwd(), yamlPath)
- // Step 1: Extract source issue URLs.
spinner.start('Parsing release notes file...')
const sourceNotes = extractSourceNotes(yamlPath)
spinner.succeed(`Found ${sourceNotes.length} unique release issue(s) in ${relativeFilePath}`)
@@ -249,7 +224,6 @@ program
process.exit(0)
}
- // Step 2: Check for existing comments (avoid duplicates).
const releaseType = rc ? 'rc' : 'ga'
const marker = buildMarker(release, releaseType)
const alreadyCommented = new Set<number>()
@@ -268,7 +242,7 @@ program
alreadyCommented.add(note.issueNumber)
}
} catch {
- // If we can't read comments, we'll try to post and handle errors then
+ // Post anyway when comment reads fail; posting reports permission errors.
}
}
if (alreadyCommented.size > 0) {
@@ -282,7 +256,6 @@ program
spinner.succeed('No existing notifications found')
}
- // Step 3: Post comments.
const toNotify = sourceNotes.filter((n) => !alreadyCommented.has(n.issueNumber))
if (toNotify.length === 0) {
@@ -295,18 +268,17 @@ program
for (let i = 0; i < toNotify.length; i++) {
const note = toNotify[i]
- // Fetch assignees (or fall back to issue author) for the release issue
+ // Mention assignees, or the non-bot issue author when no assignee exists.
let assignees: string[] = []
try {
const raw = ghRead(['api', `repos/github/releases/issues/${note.issueNumber}`])
const issue = JSON.parse(raw)
assignees = (issue.assignees || []).map((a: { login: string }) => a.login)
- // Fall back to the issue author unless they're a bot
if (assignees.length === 0 && issue.user?.login && issue.user.type !== 'Bot') {
assignees = [issue.user.login]
}
} catch {
- // If we can't fetch the issue, post without mentions
+ // Post without mentions when the issue fetch fails.
}
const commentBody = buildCommentBody(release, rc, prNumber, assignees)
@@ -342,7 +314,6 @@ program
}
}
- // Summary.
console.log(`\n${'─'.repeat(40)}`)
console.log(`${dryRun ? '🔍 Dry run' : '✅ Done'}`)
console.log(
@@ -356,7 +327,7 @@ program
},
)
-// Only run CLI when executed directly (not when imported in tests)
+// Tests import helpers without running the CLI.
if (import.meta.url === `file://${process.argv[1]}`) {
program.parse(process.argv)
}
diff --git a/src/ghes-releases/scripts/release-banner.ts b/src/ghes-releases/scripts/release-banner.ts
index 7c2136cb64b4..64f15e74c3f1 100644
--- a/src/ghes-releases/scripts/release-banner.ts
+++ b/src/ghes-releases/scripts/release-banner.ts
@@ -1,12 +1,5 @@
-/**
- * @purpose Writer tool
- * @description Create or remove a release candidate banner for a GHES version
- */
-// [start-readme]
-//
-// This script creates or removes a release candidate banner for a specified version.
-//
-// [end-readme]
+// @purpose Writer tool
+// @description Create or remove a release candidate banner for a GHES version
import fs from 'fs/promises'
import { program } from 'commander'
diff --git a/src/ghes-releases/scripts/update-enterprise-dates.ts b/src/ghes-releases/scripts/update-enterprise-dates.ts
index 2eff3bc7c721..6a3a3bb12f1d 100644
--- a/src/ghes-releases/scripts/update-enterprise-dates.ts
+++ b/src/ghes-releases/scripts/update-enterprise-dates.ts
@@ -1,13 +1,9 @@
-/**
- * @purpose Writer tool
- * @description Update enterprise release dates from github/enterprise-releases
- */
-// [start-readme]
+// @purpose Writer tool
+// @description Update enterprise release dates from github/enterprise-releases
//
-// This script fetches data from https://github.com/github/enterprise-releases/blob/master/releases.json
-// and updates `src/ghes-releases/lib/enterprise-dates.json`, which the site uses for various functionality.
-//
-// [end-readme]
+// Fetches https://github.com/github/enterprise-releases/blob/master/releases.json
+// and updates src/ghes-releases/lib/enterprise-dates.json.
+// enterprise-dates.json supplies site release date behavior.
import { fileURLToPath } from 'url'
import path from 'path'
@@ -17,10 +13,11 @@ import { getContents } from '@/workflows/git-utils'
interface EnterpriseDates {
[releaseNumber: string]: {
- releaseDate: string // For backward compatibility - RC date initially, then GA date once available
+ // Keep releaseDate as the RC date until a GA date exists for backward compatibility.
+ releaseDate: string
deprecationDate: string
- releaseCandidateDate?: string // Release Candidate date
- generalAvailabilityDate?: string // General Availability date
+ releaseCandidateDate?: string
+ generalAvailabilityDate?: string
}
}
@@ -36,7 +33,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url))
const enterpriseDatesFile = path.join(__dirname, '../lib/enterprise-dates.json')
const enterpriseDatesString = await fs.readFile(enterpriseDatesFile, 'utf8')
-// check for required PAT
+// getContents requires GITHUB_TOKEN.
if (!process.env.GITHUB_TOKEN) {
throw new Error('Error! You must have a GITHUB_TOKEN set in an .env file to run this script.')
}
@@ -59,7 +56,7 @@ async function main(): Promise<void> {
const formattedDates: EnterpriseDates = {}
for (const [releaseNumber, releaseObject] of Object.entries(rawDates)) {
formattedDates[releaseNumber] = {
- // For backward compatibility, keep releaseDate as RC date initially, then GA date once available
+ // Keep releaseDate as the RC date until a GA date exists for backward compatibility.
releaseDate: releaseObject.release_candidate || releaseObject.start,
deprecationDate: releaseObject.end,
releaseCandidateDate: releaseObject.release_candidate,
diff --git a/src/ghes-releases/scripts/version-utils.ts b/src/ghes-releases/scripts/version-utils.ts
index 9e71b1d7cd63..f6fe47d63cdb 100644
--- a/src/ghes-releases/scripts/version-utils.ts
+++ b/src/ghes-releases/scripts/version-utils.ts
@@ -4,15 +4,12 @@ import { supported } from '@/versions/lib/enterprise-server-releases'
import getDataDirectory from '@/data-directory/lib/data-directory'
import { FeatureData, FrontmatterVersions } from '@/types'
-// Return true if lowestSupportedVersion > semVerRange
export function isGhesReleaseDeprecated(lowestSupportedVersion: string, semVerRange: string) {
const lowestSemver = semver.coerce(lowestSupportedVersion)
if (!lowestSemver) return false
return semver.gtr(lowestSemver.version, semVerRange)
}
-// Return true if the semver range is greater than the
-// lowest supported GHES version
export function isInAllGhes(semverRange: string) {
if (semverRange === '*') return true
const regexGt = /(>|>=){1}\s?(\d+\.\d+)/g
@@ -27,11 +24,8 @@ export function isInAllGhes(semverRange: string) {
return semver.lte(minVersion, oldestSupported)
}
-// A feature is deprecated if it only contains
-// GHES releases and all releases are deprecated
-// or all releases are supported.
+// GHES-only features disappear when their GHES range is fully deprecated.
export function isFeatureDeprecated(versions: FrontmatterVersions) {
- // All GHES releases are deprecated
return (
!!versions.ghes &&
!versions.fpt &&
@@ -40,8 +34,6 @@ export function isFeatureDeprecated(versions: FrontmatterVersions) {
)
}
-// Return true when the feature version is in all versions
-// and all GHES releases.
export function isAllVersions(versions: FrontmatterVersions) {
if (
versions &&
diff --git a/src/ghes-releases/tests/generate-release-notes.ts b/src/ghes-releases/tests/generate-release-notes.ts
index a656f6d0125d..02aee8cf6988 100644
--- a/src/ghes-releases/tests/generate-release-notes.ts
+++ b/src/ghes-releases/tests/generate-release-notes.ts
@@ -270,7 +270,6 @@ describe('buildReleaseNotesYaml', () => {
const reposIdx = yaml.indexOf('- heading: Repositories')
expect(actionsIdx).toBeGreaterThan(-1)
expect(reposIdx).toBeGreaterThan(-1)
- // GitHub Actions comes before Repositories in featureHeadings
expect(actionsIdx).toBeLessThan(reposIdx)
expect(yaml).toContain('Actions note.')
@@ -283,7 +282,6 @@ describe('buildReleaseNotesYaml', () => {
]
const yaml = buildReleaseNotesYaml(entries, false, featureHeadings)
- // Should appear under changes, not features
expect(yaml).toContain(' features:\n # TODO: Add feature notes')
expect(yaml).toContain(' changes:')
expect(yaml).toContain('# https://example.com/1')
@@ -305,7 +303,6 @@ describe('buildReleaseNotesYaml', () => {
expect(yaml).toContain('Deprecating X.')
expect(yaml).toContain(' retired:\n # https://example.com/2')
expect(yaml).toContain('Removed Y.')
- // Changes should be omitted since Closing down/Retired are excluded and no other entries exist
expect(yaml).not.toContain(' changes:')
})
@@ -314,8 +311,7 @@ describe('buildReleaseNotesYaml', () => {
expect(yaml).toContain('# TODO: Add feature notes')
expect(yaml).toContain('# TODO: Add known issues')
- // Empty changes, closing_down, and retired are omitted entirely
- // to avoid YAML parsing as null (which fails schema validation)
+ // Omit empty changes, closing_down, and retired so schema validation does not see null sections.
expect(yaml).not.toContain(' changes:')
expect(yaml).not.toContain(' closing_down:')
expect(yaml).not.toContain(' retired:')
diff --git a/src/ghes-releases/tests/notify-release-pms.ts b/src/ghes-releases/tests/notify-release-pms.ts
index d9e87a09cd8f..33eea75582e6 100644
--- a/src/ghes-releases/tests/notify-release-pms.ts
+++ b/src/ghes-releases/tests/notify-release-pms.ts
@@ -100,8 +100,7 @@ describe('buildCommentBody', () => {
})
describe('duplicate-prevention filtering', () => {
- // This tests the core filtering logic used in the CLI action:
- // const toNotify = sourceNotes.filter((n) => !alreadyCommented.has(n.issueNumber))
+ // These tests cover duplicate filtering without running the CLI action.
const sourceNotes: SourceNote[] = [
{ issueUrl: 'https://github.com/github/releases/issues/100', issueNumber: 100 },
@@ -133,7 +132,6 @@ describe('duplicate-prevention filtering', () => {
const marker = buildMarker('3.21', 'rc')
const commentBody = buildCommentBody('3.21', true, 100, ['octocat'])
- // Simulates the duplicate-check logic: comments.includes(marker)
expect(commentBody.includes(marker)).toBe(true)
})
@@ -145,7 +143,6 @@ describe('duplicate-prevention filtering', () => {
})
test('new issues added after initial run are not excluded', () => {
- // Simulates: ran script once for issues 100+200, then re-run after adding 300
const alreadyCommented = new Set([100, 200])
const updatedSourceNotes: SourceNote[] = [
...sourceNotes,
diff --git a/src/github-apps/lib/index.ts b/src/github-apps/lib/index.ts
index 9fef828acf55..cd3debd429fb 100644
--- a/src/github-apps/lib/index.ts
+++ b/src/github-apps/lib/index.ts
@@ -16,11 +16,10 @@ interface AppsConfig {
// parameter on getAppsData.
type AppsData = Record<string, unknown>
-// Deduplicated on-disk format types.
-// A leaf entry in the shared pool: an operation or permission object.
+// A shared pool entry contains one operation or permission object.
type SharedAppsEntry = Record<string, unknown>
-// Per-page index for permission pages: permName → metadata + indices into the pool.
+// Permission pages map each permission name to metadata and shared-entry indices.
interface PermissionsPageIndex {
[permName: string]: {
title: string
@@ -29,14 +28,14 @@ interface PermissionsPageIndex {
}
}
-// Per-page index for rest pages: category → indices into the pool.
+// REST pages map each category to shared-entry indices.
interface RestPageIndex {
[category: string]: number[]
}
type AppsPageIndex = PermissionsPageIndex | RestPageIndex
-// version-index.json: version → pageType → page index.
+// version-index.json maps each OpenAPI version and page type to a page index.
type AppsVersionIndex = Record<string, Record<string, AppsPageIndex>>
const logger = createLogger(import.meta.url)
@@ -48,9 +47,8 @@ let sharedEntries: SharedAppsEntry[] | null = null
let sharedVersionIndex: AppsVersionIndex | null = null
let sharedFormatAvailable: boolean | null = null
-// A missing shared-format file is expected (per-version files are the fallback),
-// but a corrupt or unparseable file should fail loudly rather than silently
-// degrade to the per-version files and hide bad generated data.
+// A missing shared-format file is expected because per-version files are the fallback.
+// Corrupt or unparseable files fail loudly instead of hiding bad generated data.
function isFileNotFoundError(err: unknown): boolean {
if (!(err instanceof Error) || !('code' in err)) return false
const code = (err as NodeJS.ErrnoException).code
@@ -66,8 +64,7 @@ function loadSharedAppsFormat(): boolean {
sharedVersionIndex = readCompressedJsonFileFallback(
path.join(ENABLED_APPS_DIR, 'version-index.json'),
) as AppsVersionIndex
- // Freeze pool data so reconstructed objects (which return references into
- // the pool) can't be mutated by downstream code and leak across versions.
+ // Freeze pool entries so downstream mutations cannot leak through shared version objects.
Object.freeze(sharedEntries)
for (const entry of sharedEntries) Object.freeze(entry)
sharedFormatAvailable = true
@@ -86,8 +83,7 @@ function loadSharedAppsFormat(): boolean {
return sharedFormatAvailable
}
-// Resolves a pool index into its entry, throwing a clear error if the index is
-// out of bounds (e.g. from a stale or corrupt version-index.json).
+// Resolve a pool index and report stale or corrupt version-index.json pointers.
function resolveSharedEntry(
idx: number,
pageType: string,
@@ -116,7 +112,6 @@ function reconstructAppsFromSharedFormat(
const isPermissions = pageType.includes('permissions')
if (isPermissions) {
- // Reconstruct permission data: { permName: { title, displayTitle, permissions: [...] } }
const result: Record<string, { title: string; displayTitle: string; permissions: unknown[] }> =
{}
for (const [permName, meta] of Object.entries(pageData as PermissionsPageIndex)) {
@@ -128,7 +123,6 @@ function reconstructAppsFromSharedFormat(
}
return result
} else {
- // Reconstruct rest data: { category: [...operations] }
const result: Record<string, unknown[]> = {}
for (const [category, indices] of Object.entries(pageData as RestPageIndex)) {
result[category] = indices.map((idx) => resolveSharedEntry(idx, pageType, openApiVersion))
@@ -137,8 +131,6 @@ function reconstructAppsFromSharedFormat(
}
}
-// Initialize the Map with the page type keys listed under `pages`
-// in the config.json file.
const appsDataConfig: AppsConfig = JSON.parse(
fs.readFileSync('src/github-apps/lib/config.json', 'utf8'),
)
@@ -161,8 +153,7 @@ export async function getAppsData<T extends AppsData = AppsData>(
if (data) {
pageTypeMap.set(openApiVersion, data)
} else {
- // Fall back to per-version JSON.
- // readCompressedJsonFileFallback checks for both a .br and a .json extension.
+ // Fall back to per-version .br or .json files when shared data is unavailable.
const appDataPath = path.join(ENABLED_APPS_DIR, openApiVersion, filename)
pageTypeMap.set(openApiVersion, readCompressedJsonFileFallback(appDataPath) as AppsData)
}
@@ -198,9 +189,7 @@ export async function getAppsServerSideProps(
const titles: string[] = useDisplayTitle
? Object.values(appsItems).map((item) => (item as AppsItemWithDisplayTitle).displayTitle!)
: Object.keys(appsItems)
- // getAutomatedPageMiniTocItems expects a `Context`, but this code path has
- // always passed Next.js's GetServerSidePropsContext at runtime.
- // Hence the double assertion.
+ // This path passes GetServerSidePropsContext where getAutomatedPageMiniTocItems expects Context.
const appMiniToc = await getAutomatedPageMiniTocItems(titles, context as unknown as Context)
if (appMiniToc) {
miniTocItems.push(...appMiniToc)
diff --git a/src/github-apps/scripts/enabled-list-schema.ts b/src/github-apps/scripts/enabled-list-schema.ts
index 75ee13712d98..11675dac0ee1 100644
--- a/src/github-apps/scripts/enabled-list-schema.ts
+++ b/src/github-apps/scripts/enabled-list-schema.ts
@@ -1,7 +1,6 @@
-// This schema is used to validate
-// src/github-apps/data/server-to-server-rest.json
-// src/github-apps/data/user-to-server-rest.json
-// and src/github-apps/data/fine-grained-pat.json
+// This schema validates src/github-apps/data/server-to-server-rest.json,
+// src/github-apps/data/user-to-server-rest.json,
+// and src/github-apps/data/fine-grained-pat.json.
interface SchemaProperty {
description: string
diff --git a/src/github-apps/scripts/permission-list-schema.ts b/src/github-apps/scripts/permission-list-schema.ts
index a30ecd52c2dc..b9d0cd1af105 100644
--- a/src/github-apps/scripts/permission-list-schema.ts
+++ b/src/github-apps/scripts/permission-list-schema.ts
@@ -1,6 +1,5 @@
-// This schema is used to validate
-// src/github-apps/data/fine-grained-pat-permissions.json
-// and src/github-apps/data/server-to-server-permissions.json
+// This schema validates src/github-apps/data/fine-grained-pat-permissions.json
+// and src/github-apps/data/server-to-server-permissions.json.
interface SchemaProperty {
type: string
@@ -49,7 +48,7 @@ const schema: Schema = {
type: 'object',
required: ['title', 'displayTitle', 'permissions'],
properties: {
- // Properties from the source OpenAPI schema that this module depends on
+ // Generated permission entries combine metadata titles with assembled permission rows.
title: {
description: 'The name of the permission.',
type: 'string',
diff --git a/src/github-apps/scripts/sync.ts b/src/github-apps/scripts/sync.ts
index b9c1f7d84ae7..22f26242bccd 100755
--- a/src/github-apps/scripts/sync.ts
+++ b/src/github-apps/scripts/sync.ts
@@ -13,7 +13,7 @@ import { validateJson } from '@/tests/lib/validate-json-schema'
const ENABLED_APPS_DIR = 'src/github-apps/data'
const CONFIG_FILE = 'src/github-apps/lib/config.json'
-// Actor type mapping from generic names to actual YAML values
+// Map generic actor names to excluded_actors values.
export const actorTypeMap: Record<string, string> = {
fine_grained_pat: 'fine_grained_personal_access_token',
server_to_server: 'github_app',
@@ -134,8 +134,7 @@ export async function syncGitHubAppsData(
for (const pageType of Object.keys(appsDataConfig.pages)) {
githubAppsData[pageType] = {}
}
- // Because the information used on the apps page doesn't require any
- // rendered content we can parse the dereferenced files directly
+ // Apps pages only need operation metadata here, so parse dereferenced OpenAPI files directly.
for (const [requestPath, operationsAtPath] of Object.entries(schemaData.paths)) {
for (const [verb, operation] of Object.entries(operationsAtPath)) {
if (!progAccessData[operation.operationId]) continue
@@ -191,12 +190,6 @@ export async function syncGitHubAppsData(
progAccessData[operation.operationId].permissions,
)
- // Filter out metadata permissions when combined with other permissions
- // The metadata permission is automatically granted with any other repository permission,
- // so documenting it for operations that require additional permissions is misleading.
- // This fixes the issue where mutating operations (PUT, DELETE) incorrectly appeared
- // to only need metadata access when they actually require write permissions.
- // See: https://github.com/github/docs-engineering/issues/5212
if (
shouldFilterMetadataPermission(
permissionName,
@@ -241,11 +234,7 @@ export async function syncGitHubAppsData(
const isExcluded = isActorExcluded(excludedActors, 'fine_grained_pat', actorTypeMap)
if (isFineGrainedPat && !isExcluded) {
- // Hardcoded exception: exclude repository_projects from fine-grained PAT permissions
- // This is because fine-grained PATs can only operate on organization-level Projects (classic),
- // not repository-level Projects (classic). Users cannot grant the repository Projects (classic)
- // fine-grained permission in the fine-grained PAT UI.
- // See: https://github.com/github/docs-engineering/issues/4613
+ // Fine-grained PATs grant org Projects (classic), not repo Projects (classic).
if (permissionName === 'repository_projects') {
continue
}
@@ -275,7 +264,6 @@ export async function syncGitHubAppsData(
const versionName = path.basename(schemaName, '.json')
const targetDirectory = path.join(ENABLED_APPS_DIR, versionName)
- // When a new version is added, we need to create the directory for it
if (!existsSync(targetDirectory)) {
await mkdir(targetDirectory, { recursive: true })
}
@@ -302,16 +290,16 @@ export async function syncGitHubAppsData(
await writeDeduplicatedAppsFormat()
}
+// The deduplicated format stores repeated operation and permission objects once.
+// version-index.json maps each version and page to those shared entries.
async function writeDeduplicatedAppsFormat() {
console.log(`\n▶️ Writing deduplicated GitHub Apps data...\n`)
- // Read all the per-version files we just wrote to build the shared format
const versions = fs.readdirSync(ENABLED_APPS_DIR).filter((f) => {
const fullPath = path.join(ENABLED_APPS_DIR, f)
return fs.statSync(fullPath).isDirectory() && f !== 'shared'
})
- // Pool for unique leaf objects (operations and permission entries)
const entriesPool: unknown[] = []
const entriesMap = new Map<string, number>()
@@ -324,9 +312,7 @@ async function writeDeduplicatedAppsFormat() {
return index
}
- // version-index structure:
- // For rest pages: { version: { pageType: { category: number[] } } }
- // For permission pages: { version: { pageType: { permName: { title, displayTitle, indices: number[] } } } }
+ // REST pages map categories to indices; permission pages map names to metadata and indices.
const versionIndex: Record<string, Record<string, unknown>> = {}
let totalItems = 0
@@ -339,9 +325,7 @@ async function writeDeduplicatedAppsFormat() {
const pageType = path.basename(file, '.json')
const data = JSON.parse(fs.readFileSync(path.join(versionDir, file), 'utf8'))
const isPermissions = pageType.includes('permissions')
-
if (isPermissions) {
- // Permission data: { permName: { title, displayTitle, permissions: [...] } }
const pageIndex: Record<
string,
{ title: string; displayTitle: string; indices: number[] }
@@ -359,7 +343,6 @@ async function writeDeduplicatedAppsFormat() {
}
versionIndex[version][pageType] = pageIndex
} else {
- // Rest data: { category: [...operations] }
const pageIndex: Record<string, number[]> = {}
for (const [category, operations] of Object.entries(
data as Record<string, AppDataOperation[]>,
@@ -547,7 +530,7 @@ export function calculateAdditionalPermissions(
)
}
-// Without this, a mutating operation appears to need only metadata access.
+// Metadata is redundant when any other permission applies, so hide it in those rows.
export function shouldFilterMetadataPermission(
permissionName: string,
permissionSets: Array<Record<string, string>>,
@@ -621,6 +604,7 @@ async function validateAppData(
}
}
+// Use gitHubSourceDirectory locally; use owner, repo, branch, and path remotely.
interface ProgActorResourceContentOptions {
owner?: string
repo?: string
@@ -629,11 +613,6 @@ interface ProgActorResourceContentOptions {
gitHubSourceDirectory?: string | null
}
-// When getting files from the GitHub repo locally (or in a Codespace)
-// you can pass the full or relative path to the `github` repository
-// directory on disk.
-// When the source directory is `rest-api-description` (which is more common)
-// you can pass the `owner`, `repo`, `branch`, and `path` (repository path)
async function getProgActorResourceContent({
owner,
repo,
diff --git a/src/github-apps/tests/deduplication.ts b/src/github-apps/tests/deduplication.ts
index 3a2503bec523..53cb5756b8dd 100644
--- a/src/github-apps/tests/deduplication.ts
+++ b/src/github-apps/tests/deduplication.ts
@@ -146,7 +146,7 @@ describe('GitHub Apps deduplication', () => {
}
const uniqueEntries = entries.length
- // We expect at least 70% dedup rate based on issue analysis (~84% reported)
+ // The 70% threshold leaves room for normal generated-data churn.
const dedupRate = 1 - uniqueEntries / totalReferences
expect(dedupRate).toBeGreaterThan(0.7)
})
diff --git a/src/github-apps/tests/excluded-actors.ts b/src/github-apps/tests/excluded-actors.ts
index 7cbaa790f24e..3041a1652146 100644
--- a/src/github-apps/tests/excluded-actors.ts
+++ b/src/github-apps/tests/excluded-actors.ts
@@ -44,8 +44,6 @@ describe('excluded_actors filtering', () => {
expect(isActorExcluded(['UserProgrammaticAccess'], 'fine_grained_pat', actorTypeMap)).toBe(true)
expect(isActorExcluded(['github_app'], 'server_to_server', actorTypeMap)).toBe(true)
expect(isActorExcluded(['user_access_token'], 'user_to_server', actorTypeMap)).toBe(true)
-
- // Test fallback when no mapping exists
expect(isActorExcluded(['some_unmapped_actor'], 'some_unmapped_actor')).toBe(true)
expect(isActorExcluded(['some_unmapped_actor'], 'different_actor')).toBe(false)
})
@@ -84,8 +82,6 @@ describe('excluded_actors filtering', () => {
).toBe(true)
expect(isActorExcluded(['github_app'], 'server_to_server', actorTypeMap)).toBe(true)
expect(isActorExcluded(['user_access_token'], 'user_to_server', actorTypeMap)).toBe(true)
-
- // Test fallback when no mapping exists
expect(isActorExcluded(['some_unmapped_actor'], 'some_unmapped_actor')).toBe(true)
expect(isActorExcluded(['some_unmapped_actor'], 'different_actor')).toBe(false)
})
diff --git a/src/github-apps/tests/metadata-permissions.ts b/src/github-apps/tests/metadata-permissions.ts
index 3bdc2e025b9a..a644ab30629a 100644
--- a/src/github-apps/tests/metadata-permissions.ts
+++ b/src/github-apps/tests/metadata-permissions.ts
@@ -191,12 +191,11 @@ describe('metadata permissions filtering', () => {
expect(shouldFilterMetadataPermission('metadata', metadataInSeparateSet)).toBe(true)
})
+ // PUT and DELETE /orgs/{org}/actions/permissions/repositories/{repository_id}
+ // pair metadata with organization_administration.
test('filters metadata permissions that match the GitHub issue examples', () => {
- // These are examples from the GitHub issue that should be filtered out
- // PUT /orgs/{org}/actions/permissions/repositories/{repository_id}
const putActionsPermissions = [{ metadata: 'read', organization_administration: 'write' }]
- // DELETE /orgs/{org}/actions/permissions/repositories/{repository_id}
const deleteActionsPermissions = [{ metadata: 'read', organization_administration: 'write' }]
expect(shouldFilterMetadataPermission('metadata', putActionsPermissions)).toBe(true)
@@ -278,12 +277,9 @@ describe('metadata permissions filtering', () => {
}
})
+ // PUT and DELETE /orgs/{org}/actions/permissions/repositories/{repository_id}
+ // pair metadata with organization_administration.
test('validates filtering logic matches expected behavior from issue', () => {
- // Based on the GitHub issue, these operations should be filtered out from metadata:
- // - PUT /orgs/{org}/actions/permissions/repositories/{repository_id}
- // - DELETE /orgs/{org}/actions/permissions/repositories/{repository_id}
- // Because they have metadata + organization_administration permissions
-
const progData: ProgAccessData = {
userToServerRest: true,
serverToServer: true,
diff --git a/src/github-apps/tests/rendering.ts b/src/github-apps/tests/rendering.ts
index 19ebb9ca7e78..fc3b249cb2ff 100644
--- a/src/github-apps/tests/rendering.ts
+++ b/src/github-apps/tests/rendering.ts
@@ -70,7 +70,6 @@ describe('REST references docs', () => {
apiVersion,
)
- // using the static file, generate the expected slug for each operation
for (const [key, value] of Object.entries(enabledForApps)) {
schemaSlugs.push(
...value.map(
@@ -81,7 +80,6 @@ describe('REST references docs', () => {
),
)
}
- // get all of the href attributes in the anchor tags
const contentPath = configContent.pages[page].targetFilename
.replace('content/', '')
.replace('.md', '')
@@ -94,7 +92,6 @@ describe('REST references docs', () => {
})
test('loads permission list pages', async () => {
- // permissions pages
for (const page of permissionPages) {
const schemaSlugs: string[] = []
@@ -104,7 +101,6 @@ describe('REST references docs', () => {
apiVersion,
)
- // using the static file, generate the expected slug for each operation
for (const value of Object.values(permissionsData)) {
schemaSlugs.push(
...value.permissions.map(
@@ -116,7 +112,6 @@ describe('REST references docs', () => {
)
}
- // get all of the href attributes in the anchor tags
const contentPath = configContent.pages[page].targetFilename
.replace('content/', '')
.replace('.md', '')
diff --git a/src/github-apps/tests/sync.ts b/src/github-apps/tests/sync.ts
index ec8dad3f1810..2b412bf07141 100644
--- a/src/github-apps/tests/sync.ts
+++ b/src/github-apps/tests/sync.ts
@@ -128,7 +128,7 @@ describe('getProgAccessData', () => {
const expectedData = {
userToServerRest: false,
serverToServer: true,
- fineGrainedPat: false, // false because user_to_server.enabled is false
+ fineGrainedPat: false, // user_to_server.enabled is false
permissions: [{ metadata: 'read' }],
allowPermissionlessAccess: true,
allowsPublicRead: false,
@@ -158,7 +158,6 @@ describe('getProgAccessData', () => {
const result = await processProgAccessDataMock(mockProgAccessDataRaw, mockProgActorResources)
- // All operation IDs should exist (whitespace should be trimmed)
expect(result.progAccessData).toHaveProperty('operation-a')
expect(result.progAccessData).toHaveProperty('operation-b')
expect(result.progAccessData).toHaveProperty('operation-c')
@@ -224,7 +223,7 @@ describe('getProgAccessData', () => {
const expectedCommaData = {
userToServerRest: true,
serverToServer: false,
- fineGrainedPat: false, // false because disabled_for_patv2 is true
+ fineGrainedPat: false, // disabled_for_patv2 is true
permissions: [{ metadata: 'write' }],
allowPermissionlessAccess: true,
allowsPublicRead: false,
@@ -236,8 +235,6 @@ describe('getProgAccessData', () => {
})
})
-// Helper function to simulate the data processing logic from sync.ts
-// without needing to set up the full file system or remote API calls
async function processProgAccessDataMock(
progAccessDataRaw: ProgAccessDataRaw[],
progActorResources: ProgActorResources,
@@ -255,7 +252,6 @@ async function processProgAccessDataMock(
basicAuth: operation.basic_auth,
}
- // Handle comma-separated operation IDs
const operationIds = operation.operation_ids.split(',').map((id) => id.trim())
for (const operationId of operationIds) {
progAccessData[operationId] = operationData
diff --git a/src/journeys/components/JourneyTrackNav.tsx b/src/journeys/components/JourneyTrackNav.tsx
index 0a8923691aa8..f940fbc01b72 100644
--- a/src/journeys/components/JourneyTrackNav.tsx
+++ b/src/journeys/components/JourneyTrackNav.tsx
@@ -16,8 +16,7 @@ export function JourneyTrackNav({ context }: Props) {
const upNext = nextGuide ?? nextTrackFirstGuide
if (!upNext) return null
- // In-track, show the next article's title.
- // Crossing tracks, show the track name so the reader knows they're moving on.
+ // Crossing tracks uses the track name so readers know they are moving to another track.
const label = nextGuide ? nextGuide.title : nextTrackFirstGuide!.trackTitle
const progress = t('up_next_progress')
diff --git a/src/journeys/lib/journey-path-resolver.ts b/src/journeys/lib/journey-path-resolver.ts
index 566199827fbd..ecb1640357a3 100644
--- a/src/journeys/lib/journey-path-resolver.ts
+++ b/src/journeys/lib/journey-path-resolver.ts
@@ -59,9 +59,8 @@ type JourneyPage = {
}>
}
-// All computed once, on first use.
-// Guide hrefs containing Liquid can't be resolved ahead of time,
-// so they're absent from cachedGuidePaths and set hasDynamicGuides instead.
+// Static guide paths cache on first use.
+// Rendered hrefs stay out of cachedGuidePaths and set hasDynamicGuides.
let cachedJourneyPages: JourneyPage[] | null = null
let cachedGuidePaths: Set<string> | null = null
let hasDynamicGuides = false
@@ -134,9 +133,7 @@ async function fetchGuideData(
return null
}
-/**
- * Returns null if the article isn't a guide in any journey track.
- */
+// Returns null when no journey track applies to the article and current version.
export async function resolveJourneyContext(
articlePath: string,
pages: Record<string, Page>,
@@ -159,8 +156,7 @@ export async function resolveJourneyContext(
for (const journeyPage of journeyPages) {
if (!journeyPage.journeyTracks) continue
- // Track articles inherit the landing page's versions,
- // so a journey that doesn't apply to the current version has no navigation to show.
+ // Track articles inherit landing page versions, so unmatched versions show no navigation.
if (journeyPage.versions) {
const journeyVersions = getApplicableVersions(journeyPage.versions)
if (!journeyVersions.includes(context.currentVersion || '')) {
@@ -187,8 +183,7 @@ export async function resolveJourneyContext(
() => guidePath,
)
} catch {
- // executeWithFallback rethrows errors it can't fall back from,
- // such as any error in English.
+ // executeWithFallback rethrows non-fallbackable errors and all English content errors.
renderedGuidePath = guidePath
}
}
@@ -205,7 +200,7 @@ export async function resolveJourneyContext(
const alternativeNextStep = track.guides[guideIndex].alternativeNextStep || ''
let renderedAlternativeNextStep = alternativeNextStep
- // Rendered with links intact, unlike the hrefs above which use textOnly.
+ // Render this with links intact, unlike the hrefs above that use textOnly.
if (needsRendering(alternativeNextStep)) {
try {
renderedAlternativeNextStep = await executeWithFallback(
@@ -218,8 +213,7 @@ export async function resolveJourneyContext(
}
}
- // fetchGuideData returns null for guides missing in the current version.
- // Dropping them keeps the counts and prev/next links correct.
+ // Drop guides that fail lookup so counts and prev/next links use resolvable guides.
const availableGuides = (
await Promise.all(
track.guides.map(async (guide, i) => {
@@ -285,9 +279,7 @@ export async function resolveJourneyContext(
return result
}
-/**
- * Reads journey tracks from frontmatter, rendering any Liquid they contain.
- */
+// Journey track frontmatter may contain Liquid, so render it before components use it.
export async function resolveJourneyTracks(
journeyTracks: JourneyPage['journeyTracks'],
context: Context,
diff --git a/src/journeys/middleware/journey-track.ts b/src/journeys/middleware/journey-track.ts
index dd06002faa59..5e63d0f5ab14 100644
--- a/src/journeys/middleware/journey-track.ts
+++ b/src/journeys/middleware/journey-track.ts
@@ -38,12 +38,11 @@ export default async function journeyTrack(
if (page.journeyTracks) {
const resolvedTracks = await resolveJourneyTracks(page.journeyTracks, req.context)
- // Read later by getServerSideProps.
+ // getServerSideProps reads resolvedJourneyTracks from the page object.
page.resolvedJourneyTracks = resolvedTracks
}
- // Unconditional, because guide articles need this
- // even though they carry no journeyTracks of their own.
+ // Resolve every article because guide pages do not carry their own journeyTracks.
const journeyContext = await resolveJourneyContext(
req.pagePath || '',
req.context.pages || {},
diff --git a/src/journeys/tests/journey-path-resolver.ts b/src/journeys/tests/journey-path-resolver.ts
index e037a54309b0..e7afb804e4ad 100644
--- a/src/journeys/tests/journey-path-resolver.ts
+++ b/src/journeys/tests/journey-path-resolver.ts
@@ -4,8 +4,7 @@ import { resolveJourneyContext, resolveJourneyTracks } from '../lib/journey-path
import getLinkData from '@/journeys/lib/get-link-data'
import type { Page } from '@/types'
-// Mock modules since we just want to test journey functions, not their dependencies or
-// against real content files
+// Mock dependencies so journey functions run without real content files.
vi.mock('@/journeys/lib/get-link-data', () => ({
default: vi.fn(async (rawLinks: string | string[] | undefined) => {
const path = Array.isArray(rawLinks) ? rawLinks[0] : rawLinks
@@ -191,7 +190,6 @@ describe('journey-path-resolver', () => {
mockContext,
)
- // This should find the same track as the version with leading slash
expect(result?.trackId).toBe('getting_started')
expect(result?.currentGuideIndex).toBe(1)
})
@@ -235,7 +233,7 @@ describe('journey-path-resolver', () => {
test('renders liquid templates in titles and descriptions', async () => {
const result = await resolveJourneyTracks(mockJourneyTracks, mockContext)
- // Should return the content as-is since our mock renderContent is a passthrough
+ // The mock renderContent returns input unchanged.
expect(result[0].title).toBe(
'Getting started with {% data variables.product.company_short %}',
)
@@ -252,15 +250,14 @@ describe('journey-path-resolver', () => {
expect(result[0].timeCommitment).toBe('{% data variables.product.company_short %} 2-4 hours')
expect(result[1].timeCommitment).toBe('4-6 hours')
- // The Liquid-bearing timeCommitment should be rendered with { textOnly: true },
- // matching how title/description are rendered.
+ // Liquid timeCommitment renders with textOnly, matching titles and descriptions.
const timeCommitmentCall = mockRenderContent.mock.calls.find(
([content]) => content === '{% data variables.product.company_short %} 2-4 hours',
)
expect(timeCommitmentCall).toBeDefined()
expect(timeCommitmentCall?.[2]).toEqual({ textOnly: true })
- // Plain (non-Liquid) timeCommitment should not be sent through renderContent
+ // Plain timeCommitment skips renderContent.
const plainCall = mockRenderContent.mock.calls.find(([content]) => content === '4-6 hours')
expect(plainCall).toBeUndefined()
})
diff --git a/src/languages/lib/correct-translation-content.ts b/src/languages/lib/correct-translation-content.ts
index d7966b6a3598..b93717184066 100644
--- a/src/languages/lib/correct-translation-content.ts
+++ b/src/languages/lib/correct-translation-content.ts
@@ -1811,6 +1811,8 @@ export function correctTranslatedContentStrings(
content = content.replaceAll('<b></b>', '')
content = content.replaceAll('<u></u>', '')
+ content = content.replace(/<\/?c\d+\s*\/?>/g, '')
+
content = content.replace(/(\{%-? )ifversion-([a-z][\w-]*\s*%\})/g, '$1ifversion $2')
content = content.replaceAll('["AUTOTITLE]', '"[AUTOTITLE]')
diff --git a/src/languages/tests/correct-translation-content.ts b/src/languages/tests/correct-translation-content.ts
index 5a49ba4c2cdb..485d5778cec9 100644
--- a/src/languages/tests/correct-translation-content.ts
+++ b/src/languages/tests/correct-translation-content.ts
@@ -2998,6 +2998,32 @@ Para más información, consulta "[AUTOTITLE](/path)".
})
})
+ describe('universal: strips leftover CAT-tool <cN> placeholder tags', () => {
+ test('strips paired <c0>...</c0> tags around text', () => {
+ expect(fix('Use the <c0>Create an issue</c0> endpoint.', 'es')).toBe(
+ 'Use the Create an issue endpoint.',
+ )
+ })
+
+ test('strips self-closing <c0/> and unmatched closing tags', () => {
+ expect(fix('See the note.<c0/> More text.</c1>', 'ja')).toBe('See the note. More text.')
+ })
+
+ test('strips nested and numbered <cN> tags', () => {
+ expect(
+ fix(
+ '<c1>repositorio especificado octocat/Spoon-Knife<c3>.<c4> Reemplace `REPO-NAME`',
+ 'es',
+ ),
+ ).toBe('repositorio especificado octocat/Spoon-Knife. Reemplace `REPO-NAME`')
+ })
+
+ test('leaves content without <cN> tags unchanged', () => {
+ const correct = 'Use the Create an issue endpoint.'
+ expect(fix(correct, 'es')).toBe(correct)
+ })
+ })
+
describe('ja: github-token-scope-descriptions.md per-file fix', () => {
test('restores the missing endif in the security-events row', () => {
const broken =
diff --git a/src/observability/lib/failbot.ts b/src/observability/lib/failbot.ts
index e2b90878c26e..dbd89c203edb 100644
--- a/src/observability/lib/failbot.ts
+++ b/src/observability/lib/failbot.ts
@@ -26,6 +26,8 @@ async function retryingFetch(input: RequestInfo | URL, init?: RequestInit): Prom
return response
}
+// Failbot additional_data only accepts flat string and number values, so keep requestUuid.
+// https://github.com/github/failbotg/blob/main/docs/api.md#additional-data
export function report(error: Error, metadata?: Record<string, unknown>) {
if (!process.env.HAYSTACK_URL) {
return
@@ -42,9 +44,6 @@ export function report(error: Error, metadata?: Record<string, unknown>) {
backends,
})
- // Metadata can only be a flat object with string & number values,
- // so only add the requestUuid.
- // https://github.com/github/failbotg/blob/main/docs/api.md#additional-data
const loggerContext = getLoggerContext()
return failbot.report(error, {
@@ -53,7 +52,7 @@ export function report(error: Error, metadata?: Record<string, unknown>) {
})
}
-// Kept so legacy callers can keep doing `FailBot.report(myError)`.
+// Preserves FailBot.report(error) for existing callers.
export default {
report,
}
diff --git a/src/observability/lib/handle-package-not-found.ts b/src/observability/lib/handle-package-not-found.ts
index 8bb738532c08..80c6c122d19b 100644
--- a/src/observability/lib/handle-package-not-found.ts
+++ b/src/observability/lib/handle-package-not-found.ts
@@ -1,14 +1,8 @@
-/*
-This file adds a custom error message if a package is missing
-to prompt the contributor to run `npm ci`.
-This handler must be separate from handle-exceptions.ts in order to function.
-It's imported in package.json in nodemonConfig,
-whereas that is imported in start-server.ts.
-This file must not import any packages.
-We are suggesting `npm ci` to contributors
-to avoid unexpected changes to the package-lock.json file.
-All other errors should fall through to the error handler in handle-exceptions.ts.
-*/
+// Shows a custom npm ci prompt for missing-package errors.
+// Recommend npm ci instead of npm install to avoid unexpected package-lock.json changes.
+// package.json loads this file through nodemonConfig before start-server.ts loads handle-exceptions.ts.
+// Keep it dependency-free so missing packages can reach this handler.
+// Other uncaught exceptions fall through to handle-exceptions.ts.
type ErrorWithCode = {
code: string
diff --git a/src/observability/lib/runtime-metrics.ts b/src/observability/lib/runtime-metrics.ts
index 42740357f5af..695681cceefa 100644
--- a/src/observability/lib/runtime-metrics.ts
+++ b/src/observability/lib/runtime-metrics.ts
@@ -1,13 +1,7 @@
-/**
- * Periodically emits Node.js runtime metrics to Datadog via StatsD.
- *
- * Covers three categories that are otherwise invisible:
- * 1. V8 heap: used vs limit, so we can spot memory pressure before OOMs.
- * 2. GC: pause duration, so we can correlate latency spikes with GC.
- * 3. Event-loop delay: p50/p99, so we can see when the loop is blocked.
- *
- * Only activates when StatsD is sending real metrics (MODA_PROD_SERVICE_ENV).
- */
+// Emits runtime metrics that StatsD does not capture elsewhere:
+// V8 heap usage and limit for memory pressure, GC pause duration for latency correlation,
+// and event-loop p50 and p99 delay for blocked-loop detection.
+// Starts only when StatsD sends real metrics through MODA_PROD_SERVICE_ENV.
import v8 from 'node:v8'
import { monitorEventLoopDelay, PerformanceObserver } from 'node:perf_hooks'
@@ -21,9 +15,7 @@ function isMetricsEnabled(): boolean {
return process.env.MODA_PROD_SERVICE_ENV === 'true' && process.env.NODE_ENV !== 'test'
}
-/**
- * Call once at server start. Safe to call multiple times (no-op after first).
- */
+// Safe to call from multiple server-start paths; calls after the first are no-ops.
export function startRuntimeMetrics(): void {
if (started) return
started = true
@@ -43,8 +35,7 @@ export function startRuntimeMetrics(): void {
const gcObserver = new PerformanceObserver((list) => {
for (const entry of list.getEntries()) {
const kind = (entry as unknown as { detail?: { kind?: number } }).detail?.kind
- // kind: 1 = Scavenge (minor), 2 = Mark-Sweep-Compact (major),
- // 4 = Incremental marking, 8 = Process weak callbacks, 15 = All
+ // perf_hooks GC kinds: 1 minor, 4 major, 8 incremental, 16 weak callbacks.
const tag = kind === 1 ? 'minor' : kind === 2 ? 'major' : 'other'
statsd.histogram('node.gc.pause', entry.duration, [`gc_type:${tag}`])
}
diff --git a/src/observability/lib/statsd.ts b/src/observability/lib/statsd.ts
index ff8254d18ffe..5690a54237df 100644
--- a/src/observability/lib/statsd.ts
+++ b/src/observability/lib/statsd.ts
@@ -11,17 +11,15 @@ const {
const mock = NODE_ENV === 'test' || MODA_PROD_SERVICE_ENV !== 'true'
-// MODA_APP_NAME gets set when the deploy target is Moda
+// Moda deploys set MODA_APP_NAME for tagging.
const modaApp = MODA_APP_NAME ? `moda_app_name:${MODA_APP_NAME}` : false
const tagCandidates = ['app:docs', modaApp]
export const tags: string[] = tagCandidates.filter((tag): tag is string => Boolean(tag))
const statsd = new StatsD({
- // hot-shots falls back to DD_AGENT_HOST and DD_DOGSTATSD_PORT,
- // then to localhost:8125.
- // Moda defines DD_DOGSTATSD_PORT but not DD_AGENT_HOST,
- // and needs the host set to the Kubernetes node name from KUBE_NODE_HOSTNAME.
+ // hot-shots falls back to localhost:8125 when neither host variable is set.
+ // Moda sets only DD_DOGSTATSD_PORT, so use KUBE_NODE_HOSTNAME as the DogStatsD host.
host: DD_AGENT_HOST || KUBE_NODE_HOSTNAME,
port: DD_DOGSTATSD_PORT ? parseInt(DD_DOGSTATSD_PORT, 10) : undefined,
prefix: 'docs.',
@@ -31,10 +29,8 @@ const statsd = new StatsD({
export default statsd
-// hot-shots v14 changed asyncTimer/timer to inject a TimerContext as the
-// final argument of the wrapped function. This adapter lets callers keep
-// passing functions with their original signatures by appending an ignored
-// TimerContext parameter.
+// hot-shots asyncTimer and timer append TimerContext to wrapped functions.
+// This adapter preserves callers' original signatures by dropping that extra argument.
export function adaptForTimer<P extends unknown[], R>(
fn: (...args: P) => Promise<R>,
): (...args: [...P, TimerContext]) => Promise<R> {
diff --git a/src/observability/lib/tracing.browser.ts b/src/observability/lib/tracing.browser.ts
index c9413916387a..4eb75bd8ce42 100644
--- a/src/observability/lib/tracing.browser.ts
+++ b/src/observability/lib/tracing.browser.ts
@@ -1,3 +1 @@
-// Browser stub for tracing.ts: OTel is server-only.
-// This file is aliased in by Next.js webpack and Turbopack for client bundles.
-// It's a no-op: tracing.ts is a side-effect-only module with no exports.
+// Next.js aliases tracing.ts to this empty client-bundle stub because tracing is server-only.
diff --git a/src/observability/lib/tracing.ts b/src/observability/lib/tracing.ts
index 91f4e9ecb874..524a0b77db32 100644
--- a/src/observability/lib/tracing.ts
+++ b/src/observability/lib/tracing.ts
@@ -1,18 +1,10 @@
-// OpenTelemetry distributed tracing setup for docs-internal,
-// following the same pattern as github/alloy and github/github-ui.
-//
-// The instrumentation list (HTTP, Express, Undici/fetch) is explicit
-// instead of `getNodeAutoInstrumentations()`.
-// The "auto" helper enables ~30 instrumentations,
-// including ones that patch Node core modules (`fs`, `net`, `dns`) on every server.
-// Several of these are known to cause performance and listener-leak issues,
-// and OTel itself recommends disabling `instrumentation-fs` in production.
-// We only have HTTP traffic and outbound fetch in this app,
-// so we wire those up explicitly.
-//
-// References:
-// - https://thehub.github.com/epd/engineering/dev-practicals/observability/distributed-tracing/
-// - https://thehub.github.com/epd/engineering/dev-practicals/observability/distributed-tracing/github-telemetry-js-user-guide/
+// Follows the github/alloy and github/github-ui tracing pattern.
+// Uses explicit HTTP, Express, and Undici instrumentation instead of getNodeAutoInstrumentations.
+// The auto helper enables about 30 instrumentations, including fs, net, and dns patches.
+// These can hurt performance or leak listeners; OTel recommends disabling instrumentation-fs in production.
+// This app only needs inbound HTTP and outbound fetch tracing.
+// See https://thehub.github.com/epd/engineering/dev-practicals/observability/distributed-tracing/
+// See https://thehub.github.com/epd/engineering/dev-practicals/observability/distributed-tracing/github-telemetry-js-user-guide/
import {
CompositePropagator,
@@ -51,7 +43,7 @@ if (process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT) {
})
}
- // Uses `once` to prevent duplicate shutdown if SIGTERM is delivered multiple times.
+ // once prevents duplicate shutdown when SIGTERM arrives more than once.
process.once('SIGTERM', async () => {
try {
await sdk.shutdown()
diff --git a/src/observability/logger/index.ts b/src/observability/logger/index.ts
index 3495a799c2d0..d7cf8ff87288 100644
--- a/src/observability/logger/index.ts
+++ b/src/observability/logger/index.ts
@@ -45,7 +45,7 @@ function formatContext(ctx: Record<string, unknown>): string {
return parts.length > 0 ? ` ${parts.join(' ')}` : ''
}
-// Handles file:// URLs (from import.meta.url) and plain string labels.
+// Accepts file URLs from import.meta.url and plain string labels.
function resolveFilePath(filePath: string): string {
try {
const parsed = new URL(filePath)
@@ -76,13 +76,8 @@ interface LoggerMethod {
(message: string, ...args: (string | number | boolean | Error | IncludeContext | object)[]): void
}
-/*
-Call this function with `import.meta.url` as the argument to create a logger for a specific file.
-
-e.g. `const logger = createLogger(import.meta.url)`
-
-Logs will be output to the console in development, and in `logfmt` format to stdout in production.
-*/
+// Pass import.meta.url so logs identify the caller file.
+// Development logs go to console; production logs use logfmt on stdout.
export function createLogger(filePath: string) {
if (!filePath) {
throw new Error('createLogger must be called with the import.meta.url argument')
@@ -151,7 +146,7 @@ export function createLogger(filePath: string) {
}
const currentLogLevel = getLogLevelNumber()
if (LOG_LEVELS[level] > currentLogLevel) {
- return // Do not log if the requested level is lower priority
+ return // Higher numbers are more verbose.
}
const loggerContext = getLoggerContext()
@@ -171,7 +166,7 @@ export function createLogger(filePath: string) {
const includedContextWithFormattedError = {} as IncludeContext
for (const [key, value] of Object.entries(includeContext)) {
if (typeof value === 'object' && value instanceof Error) {
- // Errors don't serialize well to JSON, so just log the message + stack trace
+ // Errors need explicit fields because JSON serialization drops message and stack.
includedContextWithFormattedError[key] = value.message
includedContextWithFormattedError[`${key}_code`] = (value as NodeJS.ErrnoException).code
includedContextWithFormattedError[`${key}_name`] = value.name
diff --git a/src/observability/logger/lib/log-levels.ts b/src/observability/logger/lib/log-levels.ts
index fcf3fd40a419..5e63c3b14e7c 100644
--- a/src/observability/logger/lib/log-levels.ts
+++ b/src/observability/logger/lib/log-levels.ts
@@ -1,8 +1,5 @@
-/*
-The log level is controlled by the `LOG_LEVEL` environment variable, where lower
-log levels = more verbose. If log level is 'info', only 'info', 'warn', and
-'error' logs are output.
-*/
+// LOG_LEVEL controls verbosity. Lower numbers are higher priority.
+// For LOG_LEVEL=info, info, warn, and error logs are emitted.
export const LOG_LEVELS = {
error: 0,
warn: 1,
@@ -17,10 +14,8 @@ function isValidLogLevel(level: string): level is LogLevel {
return level in LOG_LEVELS
}
-// Defaults when LOG_LEVEL isn't set:
-// - 'info' in development
-// - 'debug' in production
-// - 'debug' in test, because `vitest` turns off logs unless --silent=false is passed
+// Default LOG_LEVEL is info in development and debug in production.
+// Tests default to debug because vitest suppresses logs unless --silent=false is passed.
export function getLogLevelNumber(): LogLevelValue {
let defaultLogLevel: LogLevel = 'info'
if (
diff --git a/src/observability/logger/lib/logger-context.ts b/src/observability/logger/lib/logger-context.ts
index baff1072e685..07b07308b334 100644
--- a/src/observability/logger/lib/logger-context.ts
+++ b/src/observability/logger/lib/logger-context.ts
@@ -1,9 +1,7 @@
import { AsyncLocalStorage } from 'async_hooks'
import type { NextFunction, Request, Response } from 'express'
-// Think of this like a Redux store, but for the backend.
-// An early middleware calls asyncLocalStorage.run(store, ...),
-// which lets all downstream middleware read the store via `getLoggerContext`.
+// AsyncLocalStorage carries request fields from early middleware to downstream log calls.
export const asyncLocalStorage = new AsyncLocalStorage()
export type LoggerContext = {
@@ -43,19 +41,14 @@ export function updateLoggerContext(newContext: Partial<LoggerContext>): void {
}
const INCLUDE_HEADERS = [
- // Device / UA
'user-agent',
'sec-ch-ua',
'sec-ch-ua-platform',
- // Language
'x-user-language',
'accept-language',
- // Version
'x-user-version',
- // Host
'host',
'x-host',
- // Cache control
'cache-control',
]
diff --git a/src/observability/logger/lib/to-logfmt.ts b/src/observability/logger/lib/to-logfmt.ts
index c1b5f1648243..fd0f06574818 100644
--- a/src/observability/logger/lib/to-logfmt.ts
+++ b/src/observability/logger/lib/to-logfmt.ts
@@ -1,18 +1,5 @@
-/*
- Flattens a JSON object and converts it to a logfmt string
- Nested objects are flattened with a dot separator, e.g. requestContext.path=/en
- This is because Splunk doesn't support nested JSON objects.
-
- Example
- {
- "a": 1,
- "b": {
- "c": 2
- }
- }
- becomes
- a=1 b.c=2
-*/
+// Flattens nested context for Splunk, which cannot query nested JSON objects.
+// Example: { requestContext: { path: "/en" } } becomes requestContext.path=/en.
// Matches the original node-logfmt library's quoting and escaping behavior.
function stringify(data: Record<string, unknown>): string {
@@ -46,7 +33,6 @@ function stringify(data: Record<string, unknown>): string {
line += `${key}=${stringValue} `
}
- // trim trailing space
return line.substring(0, line.length - 1)
}
diff --git a/src/observability/logger/middleware/get-automatic-request-logger.ts b/src/observability/logger/middleware/get-automatic-request-logger.ts
index 946695ace75e..5cef1caecd88 100644
--- a/src/observability/logger/middleware/get-automatic-request-logger.ts
+++ b/src/observability/logger/middleware/get-automatic-request-logger.ts
@@ -44,7 +44,7 @@ export function getAutomaticRequestLogger() {
} else if (shouldEnableAutomaticDevLogging()) {
const logLevelNum = getLogLevelNumber()
- // Don't log `/_next/` requests unless LOG_LEVEL is `debug` or higher
+ // Suppress /_next/ requests unless LOG_LEVEL is debug or more verbose.
if (url?.startsWith('/_next/') && logLevelNum < 3) {
return originalEnd.apply(this, args as Parameters<typeof originalEnd>)
}
diff --git a/src/observability/middleware/handle-errors.ts b/src/observability/middleware/handle-errors.ts
index f43857cffdf1..e0b100026de2 100644
--- a/src/observability/middleware/handle-errors.ts
+++ b/src/observability/middleware/handle-errors.ts
@@ -44,6 +44,8 @@ async function logException(error: ErrorWithCode, req: ExtendedRequest) {
}
}
+// For asset 404s, handleError sets short cache headers because Fastly caches 404 responses.
+// https://docs.fastly.com/en/guides/how-caching-and-cdns-work#http-status-codes-cached-by-default
async function handleError(
error: ErrorWithCode | number,
req: ExtendedRequest,
@@ -54,14 +56,8 @@ async function handleError(
if (req.path.startsWith('/assets') || req.path.startsWith('/_next/static')) {
if (!responseDone) {
- // Fastly caches 404s by default, so cache 404'ing assets conservatively:
- // a short Cache-Control, plus the default surrogate key
- // in case the 404 was a mistake.
- // https://docs.fastly.com/en/guides/how-caching-and-cdns-work#http-status-codes-cached-by-default
errorCacheControl(res)
- // Unsets the manual surrogate key assumed earlier in the middleware chain.
- // Falls back to `no-language` when `req.language` isn't set yet,
- // e.g. errors before language detection.
+ // Clear any earlier manual surrogate key; pre-language errors fall back to no-language.
setFastlySurrogateKey(res, makeLanguageSurrogateKey(req.language), true)
}
} else if (DEBUG_MIDDLEWARE_TESTS) {
@@ -74,7 +70,7 @@ async function handleError(
await logException(error, req)
}
- // We MUST delegate to the default Express error handler
+ // Delegate once headers are sent or the request aborted, so Express closes the connection.
next(error)
return
}
@@ -83,7 +79,7 @@ async function handleError(
req.context = {}
}
- // Special handling for when a middleware calls `next(404)`
+ // Middleware may signal a normal 404 by calling next(404).
if (error === 404) {
errorCacheControl(res)
setFastlySurrogateKey(res, makeLanguageSurrogateKey(req.language), true)
@@ -94,29 +90,26 @@ async function handleError(
throw new Error("Don't use next(xxx) where xxx is any other number than 404")
}
- // display error on the page in development and staging, but not in production
+ // Development and staging pages show the error; production pages do not.
if (!process.env.MODA_PROD_SERVICE_ENV) {
req.context.error = error
}
- // Errors with a status code usually come from a middleware like `express.json()`.
+ // Status-code errors usually come from middleware such as express.json.
if (error.statusCode) {
res.sendStatus(error.statusCode)
return
}
res.statusCode = 500
- // Local dev doesn't need the pretty HTML rendering of 500.tsx.
- // Also, as of Jan 2024, calling nextApp.renderError hangs forever
- // when `NODE_ENV` is 'development'. We can't fully explain it,
- // and it's moot because in local dev the full stack trace is more useful.
+ // In development, nextApp.renderError hangs forever and the stack trace is more useful.
if (process.env.NODE_ENV === 'development') {
next(error)
return
} else {
nextApp.renderError(error, req, res, req.path)
- // Report to Failbot AFTER responding to the user
+ // Report to Failbot after responding to the user.
await logException(error, req)
}
} catch (handlingError) {
diff --git a/src/observability/middleware/trigger-error.ts b/src/observability/middleware/trigger-error.ts
index bcd1fee9157c..7009748fe058 100644
--- a/src/observability/middleware/trigger-error.ts
+++ b/src/observability/middleware/trigger-error.ts
@@ -2,19 +2,15 @@ import type { Response, NextFunction } from 'express'
import type { ExtendedRequest } from '@/types'
-// This module is for testing our handling of uncaught async rejections on incoming requests
+// Tests use this route to exercise uncaught async rejections on incoming requests.
-// IMPORTANT: Leave this function as `async` even though it doesn't need to be!
+// Keep triggerError async and unwrapped so it rejects like async middleware.
export default async function triggerError(
req: ExtendedRequest,
res: Response,
next: NextFunction,
) {
- // IMPORTANT:
- // Do NOT wrap this method's contents in the usual `try-catch+next(error)`
- // pattern used on async middleware! This is an intentional omission!
-
- // prevent this from being used in production
+ // Block intentional errors in production.
if (process.env.NODE_ENV === 'production' && process.env.MODA_PROD_SERVICE_ENV === 'true')
return next()
diff --git a/src/observability/tests/failbot.ts b/src/observability/tests/failbot.ts
index 4aef8b831345..2084a27abab7 100644
--- a/src/observability/tests/failbot.ts
+++ b/src/observability/tests/failbot.ts
@@ -34,14 +34,11 @@ describe('FailBot', () => {
process.env.HAYSTACK_URL = 'https://haystack.example.com'
const err = new Error('Kaboom')
const backendPromises = FailBot.report(err, { foo: 'bar' })
- // Production code doesn't need to await what `FailBot.report()` returns.
- // In vitest we await now,
- // so we can assert the POST requests happened.
+ // Tests await backend promises so assertions observe the POST request.
if (backendPromises) {
await Promise.all(await backendPromises)
}
- // What `.report()` returns doesn't matter, only that it POSTed.
expect(requestBodiesSent.length).toBe(1)
expect(requestBodiesSent[0]).toMatchObject({
diff --git a/src/observability/tests/get-automatic-request-logger.ts b/src/observability/tests/get-automatic-request-logger.ts
index 0151d35321d2..1204552d4591 100644
--- a/src/observability/tests/get-automatic-request-logger.ts
+++ b/src/observability/tests/get-automatic-request-logger.ts
@@ -176,7 +176,7 @@ describe('getAutomaticRequestLogger', () => {
await new Promise((resolve) => setTimeout(resolve, 20))
- expect(consoleLogs).toHaveLength(0) // Should be filtered out
+ expect(consoleLogs).toHaveLength(0)
})
it('should log _next requests when debug level is set', async () => {
@@ -244,7 +244,6 @@ describe('getAutomaticRequestLogger', () => {
expect(consoleLogs).toHaveLength(1)
const logOutput = consoleLogs[0]
- // Should include context fields (even if empty due to mocking)
expect(logOutput).toContain('requestUuid=')
expect(logOutput).toContain('path=')
})
@@ -259,7 +258,6 @@ describe('getAutomaticRequestLogger', () => {
})
it('should not log in test environment by default', async () => {
- // Explicit environment settings for CI stability.
vi.stubEnv('NODE_ENV', 'test')
vi.stubEnv('ENABLE_DEV_LOGGING', '')
vi.stubEnv('LOG_LIKE_PRODUCTION', '')
@@ -314,7 +312,7 @@ describe('getAutomaticRequestLogger', () => {
await new Promise((resolve) => setTimeout(resolve, 20))
expect(consoleLogs).toHaveLength(1)
- expect(consoleLogs[0]).toContain('-') // Should show '-' for missing content length
+ expect(consoleLogs[0]).toContain('-')
})
it('should handle missing status code', async () => {
@@ -327,7 +325,7 @@ describe('getAutomaticRequestLogger', () => {
await new Promise((resolve) => setTimeout(resolve, 20))
expect(consoleLogs).toHaveLength(1)
- expect(consoleLogs[0]).toContain('200') // Should default to 200
+ expect(consoleLogs[0]).toContain('200')
})
it('should prefer originalUrl over url', async () => {
@@ -351,7 +349,6 @@ describe('getAutomaticRequestLogger', () => {
const startTime = Date.now()
middleware(mockReq as Request, mockRes as Response, mockNext)
- // Simulate some processing time
await new Promise((resolve) => setTimeout(resolve, 50))
;(mockRes as MockResponseWithEnd).end()
await new Promise((resolve) => setTimeout(resolve, 20))
@@ -367,7 +364,6 @@ describe('getAutomaticRequestLogger', () => {
if (responseTimeMatch) {
const loggedTime = parseInt(responseTimeMatch[1], 10)
- // Should be reasonably close to actual duration (within 20ms tolerance)
expect(loggedTime).toBeGreaterThanOrEqual(40)
expect(loggedTime).toBeLessThanOrEqual(actualDuration + 20)
}
diff --git a/src/observability/tests/logger-integration.ts b/src/observability/tests/logger-integration.ts
index c602e7243d15..9071ee9f0d74 100644
--- a/src/observability/tests/logger-integration.ts
+++ b/src/observability/tests/logger-integration.ts
@@ -16,7 +16,6 @@ function expectDevLog(logs: string[], level: string, message: string): void {
expect(match, `Expected a log containing "${level}" and "${message}"`).toBeDefined()
}
-// Integration tests that use real dependencies without mocks
describe('logger integration tests', () => {
let originalConsoleLog: typeof console.log
let originalConsoleError: typeof console.error
@@ -50,7 +49,6 @@ describe('logger integration tests', () => {
describe('logger context integration', () => {
it('should use empty context when no async local storage is set', () => {
- // Set production mode to see the context in the output
vi.stubEnv('LOG_LIKE_PRODUCTION', 'true')
vi.stubEnv('NODE_ENV', 'development')
@@ -60,7 +58,6 @@ describe('logger integration tests', () => {
expect(consoleLogs).toHaveLength(1)
const logOutput = consoleLogs[0]
- // Real getLoggerContext returns empty strings for fields when no context is set
expect(logOutput).toContain('level=info')
expect(logOutput).toContain('message="Test without context"')
expect(logOutput).toContain('timestamp=')
@@ -68,7 +65,6 @@ describe('logger integration tests', () => {
})
it('should use context from async local storage when available', async () => {
- // Set production mode to see the context in the output
vi.stubEnv('LOG_LIKE_PRODUCTION', 'true')
vi.stubEnv('NODE_ENV', 'development')
@@ -88,12 +84,9 @@ describe('logger integration tests', () => {
const mockRes = {} as unknown as Response
- // Use a Promise to handle the async local storage execution
const result = await new Promise<void>((resolve, reject) => {
- // Create a next function that will execute our test logic within the async context
const mockNext = () => {
try {
- // Update the context with additional values (simulating subsequent middleware)
updateLoggerContext({
language: 'es',
userLanguage: 'es',
@@ -144,7 +137,7 @@ describe('logger integration tests', () => {
logger.warn('Warn message')
logger.error('Error message')
- // With 'info' level, debug should be filtered out (debug=3, info=2, so debug > info)
+ // LOG_LEVEL numbers increase with verbosity, so debug 3 is filtered by info 2.
const allClean = consoleLogs.map(stripAnsi).join('\n')
expect(allClean).not.toContain('Debug message')
expectDevLog(consoleLogs, 'INFO', 'Info message')
@@ -167,7 +160,7 @@ describe('logger integration tests', () => {
logger.warn('Warn message')
logger.error('Error message')
- // With 'error' level (0), only error should be logged
+ // error 0 filters every higher-verbosity level.
const allClean = consoleLogs.map(stripAnsi).join('\n')
expect(allClean).not.toContain('Debug message')
expect(allClean).not.toContain('Info message')
@@ -197,10 +190,10 @@ describe('logger integration tests', () => {
consoleLogs.length = 0
consoleErrors.length = 0
- // Test NODE_ENV=production (but not in CI)
+ // CI disables production logging unless LOG_LIKE_PRODUCTION is true.
vi.stubEnv('NODE_ENV', 'production')
- vi.stubEnv('CI', '') // Ensure CI is not set
- vi.stubEnv('LOG_LIKE_PRODUCTION', '') // Clear this to test production detection
+ vi.stubEnv('CI', '')
+ vi.stubEnv('LOG_LIKE_PRODUCTION', '')
const logger = createLogger('file:///path/to/test.js')
logger.info('Real production logging test')
diff --git a/src/observability/tests/logger.ts b/src/observability/tests/logger.ts
index 3b446c459575..69052a424bc6 100644
--- a/src/observability/tests/logger.ts
+++ b/src/observability/tests/logger.ts
@@ -1,7 +1,7 @@
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
import { createLogger } from '@/observability/logger'
-// Mock only the logger-context for most tests, but we'll test integration without mocks
+// Most tests mock logger context; integration coverage lives in logger-integration.ts.
vi.mock('@/observability/logger/lib/logger-context')
function stripAnsi(s: string): string {
@@ -212,11 +212,11 @@ describe('createLogger', () => {
logger.error('Multiple errors', error1, error2)
- // In development mode, each error triggers a separate console.log + console.error
+ // Development logging prints one console.log and one console.error per Error.
expect(consoleLogs).toHaveLength(2)
expect(consoleErrors).toHaveLength(2)
- // Both log entries should have the same message
+ // Both Error entries share the combined message.
expectDevLog(consoleLogs, 'ERROR', 'Multiple errors: First error, Second error')
expect(consoleErrors[0]).toBe(error1)
expect(consoleErrors[1]).toBe(error2)
@@ -430,7 +430,7 @@ describe('createLogger', () => {
vi.stubEnv('KUBE_NODE_HOSTNAME', 'ghe-k8s-node-42')
vi.stubEnv('LOG_LIKE_PRODUCTION', 'true')
- // Reset modules so pod-identity is re-evaluated with the new env vars
+ // Reset modules so pod-identity reads the stubbed environment.
vi.resetModules()
const { createLogger: freshCreateLogger } = await import('@/observability/logger')
@@ -530,7 +530,7 @@ describe('createLogger', () => {
const logOutput = consoleLogs[0]
expect(logOutput).toContain('included.error="Cannot read property"')
expect(logOutput).toContain('included.error_name=TypeError')
- // When .code is undefined, error_code is present but empty
+ // Undefined error.code serializes as an empty error_code field.
expect(logOutput).toMatch(/included\.error_code= /)
expect(logOutput).toContain('included.error_stack=')
})
diff --git a/src/observability/tests/to-error.ts b/src/observability/tests/to-error.ts
index 819621bd6428..71e88aa7dc84 100644
--- a/src/observability/tests/to-error.ts
+++ b/src/observability/tests/to-error.ts
@@ -38,8 +38,7 @@ describe('toError', () => {
it('should convert undefined to an Error via JSON.stringify', () => {
const result = toError(undefined)
expect(result).toBeInstanceOf(Error)
- // JSON.stringify(undefined) returns undefined (not a string),
- // so new Error(undefined) has an empty message
+ // JSON.stringify(undefined) makes new Error(undefined) use an empty message.
expect(result.message).toBe('')
})
@@ -54,7 +53,6 @@ describe('toError', () => {
circular.self = circular
const result = toError(circular)
expect(result).toBeInstanceOf(Error)
- // String() on an object returns '[object Object]'
expect(result.message).toBe('[object Object]')
})
})
diff --git a/src/observability/tests/to-logfmt.test.ts b/src/observability/tests/to-logfmt.test.ts
index c75ff6f08df2..0f39a3cfc200 100644
--- a/src/observability/tests/to-logfmt.test.ts
+++ b/src/observability/tests/to-logfmt.test.ts
@@ -208,7 +208,7 @@ describe('toLogfmt', () => {
const result = toLogfmt(obj)
expect(result).toContain('name=test')
- expect(result).toContain('self=[Circular]') // Our implementation marks circular refs
+ expect(result).toContain('self=[Circular]')
})
it('should handle Date objects', () => {
diff --git a/src/pages/_document.tsx b/src/pages/_document.tsx
index 311fc39c040b..92d962b3d572 100644
--- a/src/pages/_document.tsx
+++ b/src/pages/_document.tsx
@@ -3,23 +3,18 @@ import Document, { Html, Head, Main, NextScript } from 'next/document'
import { defaultCSSTheme } from '@/color-schemes/components/useTheme'
import { colorModeScript } from '@/color-schemes/lib/color-mode-script'
+// MyDocument leaves SSR theme attributes at defaultCSSTheme so the HTML stays shared-cacheable.
+// colorModeScript updates them from the color_mode cookie before the browser's first paint.
+// colorModeScript injects executable JS, not content HTML, so RenderedHTML and hast do not apply.
export default class MyDocument extends Document {
render() {
return (
<Html
- // These values are always the SSR rendering defaults.
- // Before the browser's first paint, the inline `colorModeScript`
- // below updates them on the client from the `color_mode` cookie, so
- // the page paints with the user's real theme and doesn't flash. The
- // SSR defaults stay constant, so the HTML remains shared-cacheable.
data-color-mode={defaultCSSTheme.colorMode}
data-light-theme={defaultCSSTheme.lightTheme}
data-dark-theme={defaultCSSTheme.darkTheme}
>
<Head>
- {/* Inline color-mode script must run before paint to avoid a flash; it
- injects executable JS (not content HTML), so RenderedHTML/hast do
- not apply here. */}
{/* eslint-disable-next-line custom-rules/no-dangerously-set-inner-html */}
<script dangerouslySetInnerHTML={{ __html: colorModeScript }} />
</Head>
diff --git a/src/pages/_error.tsx b/src/pages/_error.tsx
index 7beaf0d627bf..6f0624d72718 100644
--- a/src/pages/_error.tsx
+++ b/src/pages/_error.tsx
@@ -18,27 +18,24 @@ function Error() {
return <GenericError />
}
+// Importing @/observability/lib/failbot here would pull it into the client bundle.
+// renderPage middleware attaches FailBot to SSR requests.
+// Excluding it in next.config.ts complicates Next.js upgrades.
Error.getInitialProps = async (ctx: NextPageContext) => {
- // `.res` only exists during SSR,
- // so its presence is how we know to send this error to Failbot.
+ // ctx.res only exists during SSR, so it gates FailBot reporting.
const { err, req, res } = ctx
let statusCode = 500
if (res?.statusCode) {
statusCode = res.statusCode
}
- // `err` is falsy for a 404, which `pages/404.tsx` handles instead.
+ // Missing pages become 404 responses in render-page, so this only reports real errors.
if (err && res && req) {
- // We can't import `@/observability/lib/failbot` here,
- // because webpack pulls this file into the client bundle.
- // Excluding it in next.config.ts would work but makes future Next.js upgrades harder.
- // Instead the contextualizers attach FailBot to the Express request,
- // so it exists only in SSR.
const expressRequest = req as unknown as ExpressRequestExtensions
const FailBot = expressRequest.FailBot
if (FailBot) {
try {
- // Allowlist: these headers carry no PII.
+ // Report only the request headers listed in OK_HEADER_KEYS.
const OK_HEADER_KEYS = ['user-agent', 'referer', 'accept-encoding', 'accept-language']
const reported = FailBot.report(err, {
path: req.url || '',
@@ -60,8 +57,7 @@ Error.getInitialProps = async (ctx: NextPageContext) => {
),
})
- // `FailBot.report()` returns undefined when no backends are configured,
- // otherwise an array of promises.
+ // FailBot.report returns undefined without backends, or an array of promises.
if (!reported) {
console.warn(
'The FailBot.report() returned undefined which means the error was NOT sent to Failbot.',
@@ -71,8 +67,7 @@ Error.getInitialProps = async (ctx: NextPageContext) => {
reported.length &&
reported.every((thing) => thing instanceof Promise)
) {
- // Await even though we ignore the results.
- // Leaving these to the event loop produces cryptic errors when one rejects.
+ // Await ignored results so rejected reports do not surface later as unclear errors.
try {
await Promise.all(reported)
} catch (error) {
@@ -80,8 +75,7 @@ Error.getInitialProps = async (ctx: NextPageContext) => {
}
}
} catch (error) {
- // This catch exists so a FailBot problem can't stop the error page from rendering.
- // It doesn't mean the report failed to send.
+ // Keep FailBot problems from blocking rendering; the report may still have sent.
console.warn('Failed to send error to FailBot.', error)
}
}
diff --git a/src/products/lib/all-products.ts b/src/products/lib/all-products.ts
index fd7dd1035eaa..7bc174d5cc89 100644
--- a/src/products/lib/all-products.ts
+++ b/src/products/lib/all-products.ts
@@ -22,7 +22,7 @@ export interface ProductMap {
[productId: string]: Product
}
-// Both internal and external products are specified in content/index.md
+// content/index.md specifies both internal and external products.
const homepage = path.posix.join(ROOT, 'content/index.md')
export const { data } = frontmatter(fs.readFileSync(homepage, 'utf8'))
@@ -35,7 +35,7 @@ for (const productId of productIds) {
const relPath = productId
const dir = path.join(ROOT, 'content', relPath)
- // Early Access may not exist in the current checkout
+ // Early Access can be absent from the current checkout.
try {
fs.readdirSync(dir)
} catch {
diff --git a/src/products/lib/get-product-groups.ts b/src/products/lib/get-product-groups.ts
index eb62a7ee8e08..e5c24643a3bd 100644
--- a/src/products/lib/get-product-groups.ts
+++ b/src/products/lib/get-product-groups.ts
@@ -10,6 +10,9 @@ import languages from '@/languages/lib/languages-server'
type PageMap = Record<string, Page>
+// childGroups stores ids such as code-security/dependabot, not localized, versioned hrefs.
+// Try the localized current-version href first, then fall back to product.versions[0]
+// from productMap.
async function getPage(
id: string,
lang: string,
@@ -21,15 +24,6 @@ async function getPage(
const external = product.external || false
- // We only have an `id` like 'code-security/dependabot',
- // so the href has to be guessed.
- // On `/fr/enterprise-server@3.9` we try
- // `/fr/enterprise-server@3.9/code-security/dependabot` first.
- // Pages aren't available in every version,
- // so the fallback is `product.versions[0]` from the `productMap`,
- // not to be confused with the `pageMap`.
- // That keeps the current version when it applies,
- // and degrades to the first when it doesn't.
let href = product.href
let name = product.name
@@ -39,9 +33,6 @@ async function getPage(
if (!external) {
href = removeFPTFromPath(path.posix.join('/', lang, context.currentVersion, id))
if (!pageMap[href]) {
- // Fall back to `product.versions[0]`.
- // For example, you're on `/en/enterprise-server@3.1`
- // but `/foo/bar` only exists in `enterprise-cloud@latest`.
if (!product.versions) throw new Error(`Product ${productId} has no versions`)
href = removeFPTFromPath(path.posix.join('/', lang, product.versions[0], id))
}
@@ -52,8 +43,7 @@ async function getPage(
)
}
- // Some should not be included for the current version, and returning
- // undefined here means this entry will be filtered out by the caller.
+ // Returning undefined lets the caller filter products unavailable in the current version.
const isFPT = context.currentVersion === 'free-pro-team@latest'
if (!isFPT && !page.applicableVersions.includes(context.currentVersion)) {
return
@@ -65,16 +55,14 @@ async function getPage(
throwIfEmpty: false,
})
}
- // Either the page didn't have a `rawShortTitle` or it was empty when
- // rendered out with Liquid. Either way, have to fall back to `rawTitle`.
+ // Fall back to rawTitle when rawShortTitle is missing or Liquid renders it empty.
if (!name || !page.rawShortTitle) {
name = await renderContentWithFallback(page, 'rawTitle', context, {
textOnly: true,
})
}
}
- // Return only the props needed for the ProductSelectionCard, since
- // that's the only place this is ever used.
+ // ProductSelectionCard only needs these props.
return {
id,
name,
@@ -147,7 +135,7 @@ export async function getProductGroups(
lang: string,
context: Context,
): Promise<ProductGroup[]> {
- // Always use English version for structure (octicon, children)
+ // Use English childGroups for octicons and children; localized files supply names only.
const englishChildGroups = data?.childGroups || []
const localizedByOcticon = await getLocalizedGroupNames(lang)
@@ -160,7 +148,7 @@ export async function getProductGroups(
name: localizedName,
icon: group.icon || null,
octicon: group.octicon || null,
- // Typically the children are product IDs, but we support deeper page paths too
+ // Children are usually product IDs, but deeper page paths are also valid.
children: (
await Promise.all(group.children.map((id: string) => getPage(id, lang, pageMap, context)))
).filter(Boolean) as ProductGroupChild[],
diff --git a/src/products/tests/get-product-groups.ts b/src/products/tests/get-product-groups.ts
index 86630f7ca13a..49f15a53d13e 100644
--- a/src/products/tests/get-product-groups.ts
+++ b/src/products/tests/get-product-groups.ts
@@ -6,7 +6,7 @@ import {
getLocalizedGroupNames,
} from '@/products/lib/get-product-groups'
-// `name` is required here to match what the library expects.
+// name matches the helper's required ProductGroupData shape.
interface MockProductGroupData {
name: string
octicon?: string
@@ -67,7 +67,7 @@ describe('get-product-groups helper functions', () => {
const localizedByOcticon: { [key: string]: string } = {
RocketIcon: 'Empezar',
ShieldLockIcon: 'Seguridad',
- CopilotIcon: 'GitHub Copilot', // Some names stay the same
+ CopilotIcon: 'GitHub Copilot',
}
const nameMap: { [key: string]: string } = mapEnglishToLocalizedNames(
@@ -90,7 +90,7 @@ describe('get-product-groups helper functions', () => {
const localizedByOcticon: { [key: string]: string } = {
RocketIcon: 'Empezar',
- // MissingIcon is not in the localized map
+ // MissingIcon has no localized entry.
}
const nameMap: { [key: string]: string } = mapEnglishToLocalizedNames(
@@ -105,16 +105,16 @@ describe('get-product-groups helper functions', () => {
})
test('handles different ordering between English and localized groups', () => {
- // English groups in one order
+ // English groups use one order.
const englishGroups: MockProductGroupData[] = [
{ name: 'Get started', octicon: 'RocketIcon', children: [] },
{ name: 'Security', octicon: 'ShieldLockIcon', children: [] },
]
- // Localized groups in different order (but mapped by octicon)
+ // Localized groups use a different order and still map by octicon.
const localizedByOcticon: { [key: string]: string } = {
- ShieldLockIcon: 'Seguridad', // Security comes first in localized
- RocketIcon: 'Empezar', // Get started comes second
+ ShieldLockIcon: 'Seguridad',
+ RocketIcon: 'Empezar',
}
const nameMap: { [key: string]: string } = mapEnglishToLocalizedNames(
@@ -142,7 +142,7 @@ describe('get-product-groups helper functions', () => {
{ name: 'GitHub Copilot', octicon: 'CopilotIcon', children: ['copilot'] },
]
- // Simulate what would come from a Spanish localized file
+ // Spanish localized index data supplies translated names with matching octicons.
const mockLocalizedChildGroups: MockProductGroupData[] = [
{ name: 'Empezar', octicon: 'RocketIcon', children: ['get-started'] },
{ name: 'Seguridad', octicon: 'ShieldLockIcon', children: ['code-security'] },
@@ -170,7 +170,7 @@ describe('get-product-groups helper functions', () => {
expect(finalResult[1].name).toBe('Seguridad')
expect(finalResult[2].name).toBe('GitHub Copilot')
- // Technical data should remain unchanged
+ // Technical data remains unchanged.
expect(finalResult[0].octicon).toBe('RocketIcon')
expect(finalResult[0].children).toEqual(['get-started'])
})
diff --git a/src/redirects/lib/exception-redirects.ts b/src/redirects/lib/exception-redirects.ts
index 131c3e175f9f..8f26a20af657 100644
--- a/src/redirects/lib/exception-redirects.ts
+++ b/src/redirects/lib/exception-redirects.ts
@@ -2,9 +2,8 @@ import fs from 'fs'
type Redirects = Record<string, string>
-// Parses the exception redirects .txt format: a bare line is a destination, and
-// each following line starting with `-` is a source that redirects to it.
-// Lines starting with `#` are comments.
+// Exception redirect files use bare destinations followed by - source lines.
+// Lines starting with # are comments.
export default function getExceptionRedirects(exceptionsTxtFile: string): Redirects {
const exceptions: Redirects = {}
const exceptionRedirectsLines = fs
diff --git a/src/redirects/lib/get-redirect.ts b/src/redirects/lib/get-redirect.ts
index 502d37fd3631..07bca4cfff59 100644
--- a/src/redirects/lib/get-redirect.ts
+++ b/src/redirects/lib/get-redirect.ts
@@ -39,13 +39,10 @@ export default function getRedirect(uri: string, context: Context): string | und
const [language, withoutLanguage] = splitPathByLanguage(uri, userLanguage)
if (withoutLanguage.startsWith('/github-ae@latest')) {
- // It has a different business logic that the rest because it's a
- // version that now will always redirect. Just a question of where to
- // exactly.
+ // githubAERedirect maps GitHub AE URLs to a non-AE destination.
const nonAERedirect = githubAERedirect(uri, context)
if (nonAERedirect.includes('/github-ae@latest')) {
- // If this happened some redirect in there didn't completely
- // get away from github-ae.
+ // GitHub AE redirects must not point back to GitHub AE.
throw new Error('Still going to github-ae@latest URL')
}
return nonAERedirect
@@ -53,15 +50,9 @@ export default function getRedirect(uri: string, context: Context): string | und
let destination: string | undefined
- // `redirects` is sourced from more than one thing. The primary use
- // case is gathering up the `redirect_from` frontmatter key.
- // But we also have `developer.json` which contains legacy redirects.
- // For example, the `developer.json` will have entries such
- // `/enterprise/v4/enum/auditlogorderfield` which clearly is using
- // the old formatting of the version. So to leverage the redirects
- // from `developer.json` we'll look at it right away.
+ // Check redirects first because developer.json has /enterprise/v4/enum/auditlogorderfield.
if (withoutLanguage in redirects) {
- // But only inject the language if it's NOT an external redirect
+ // External redirects already include their full destination.
if (redirects[withoutLanguage].includes('://')) {
return redirects[withoutLanguage]
}
@@ -71,10 +62,10 @@ export default function getRedirect(uri: string, context: Context): string | und
let basicCorrection: string | undefined
if (withoutLanguage.startsWith(nonEnterpriseDefaultVersionPrefix)) {
- // E.g. '/free-pro-team@latest/foo/bar' or '/free-pro-team@latest'
+ // Example: /free-pro-team@latest/actions or /free-pro-team@latest
basicCorrection = `/${language}${withoutLanguage.replace(nonEnterpriseDefaultVersionPrefix, '')}`
} else if (withoutLanguage.replace('/', '') in allVersions && !languagePrefixRegex.test(uri)) {
- // E.g. just '/github-ae@latest' or '/enterprise-cloud@latest'
+ // Example: /enterprise-cloud@latest
basicCorrection = `/${language}${withoutLanguage}`
return basicCorrection
}
@@ -83,23 +74,22 @@ export default function getRedirect(uri: string, context: Context): string | und
withoutLanguage === '/enterprise-server' ||
withoutLanguage.startsWith('/enterprise-server/')
) {
- // E.g. '/enterprise-server' or '/enterprise-server/3.0/foo'
+ // Example: /enterprise-server or /enterprise-server/3.0/admin
basicCorrection = `/${language}${withoutLanguage.replace(
'/enterprise-server',
`/enterprise-server@${latestStable}`,
)}`
- // If it's now just the version, without anything after, exit here
+ // Version home pages need no redirect lookup.
if (withoutLanguage === '/enterprise-server') {
return basicCorrection
}
} else if (withoutLanguage.startsWith('/enterprise-server@latest')) {
- // E.g. '/enterprise-server@latest' or '/enterprise-server@latest/3.3/foo'
+ // Example: /enterprise-server@latest or /enterprise-server@latest/3.3/admin
basicCorrection = `/${language}${withoutLanguage.replace(
'/enterprise-server@latest',
`/enterprise-server@${latestStable}`,
)}`
- // If it was *just* '/enterprise-server@latest' all that's needed is
- // the language but with 'latest' replaced with the value of `latest`
+ // Version home pages need only the language and resolved latest version.
if (withoutLanguage === '/enterprise-server@latest') {
return basicCorrection
}
@@ -107,14 +97,10 @@ export default function getRedirect(uri: string, context: Context): string | und
withoutLanguage.startsWith('/enterprise/') &&
supportedAndRecentlyDeprecated.includes(withoutLanguage.split('/')[2])
) {
- // E.g. '/enterprise/3.3' or '/enterprise/3.3/foo' or '/enterprise/3.0/foo
-
- // If the URL is without a language, and no redirect is necessary,
- // but it has as version prefix, the language has to be there
- // otherwise it will never be found in `req.context.pages`
+ // Example: /enterprise/3.3/admin needs a language prefix for req.context.pages lookup.
const version = withoutLanguage.split('/')[2]
if (withoutLanguage === `/enterprise/${version}`) {
- // E.g. `/enterprise/3.0`
+ // Example: /enterprise/3.0
basicCorrection = `/${language}${withoutLanguage.replace(
`/enterprise/${version}`,
`/enterprise-server@${version}`,
@@ -127,22 +113,19 @@ export default function getRedirect(uri: string, context: Context): string | und
)}`
}
} else if (withoutLanguage === '/enterprise') {
- // E.g. `/enterprise` exactly
+ // Example: /enterprise
basicCorrection = `/${language}/enterprise-server@${latest}`
return basicCorrection
} else if (
withoutLanguage.startsWith('/enterprise/') &&
!supported.includes(withoutLanguage.split('/')[2])
) {
- // E.g. '/en/enterprise/user/github/foo'
- // If the URL is without a language, and no redirect is necessary,
- // but it has as version prefix, the language has to be there
- // otherwise it will never be found in `req.context.pages`
+ // Example after language removal: /enterprise/user/github/actions needs a language prefix.
basicCorrection = `/${language}${withoutLanguage
.replace(`/enterprise/`, `/enterprise-server@${latest}/`)
.replace('/user/', '/')}`
} else if (withoutLanguage.startsWith('/insights')) {
- // E.g. '/insights/foo'
+ // Example: /insights/admin
basicCorrection = uri.replace('/insights', `${language}/enterprise-server@${latest}/insights`)
}
@@ -162,7 +145,7 @@ export default function getRedirect(uri: string, context: Context): string | und
withoutLanguage.split('/')[1].includes('@') &&
withoutLanguage.split('/')[1] in allVersions
) {
- // E.g. '/enterprise-server@latest' or '/github-ae@latest' or '/enterprise-server@3.3'
+ // The first segment is a known version, such as /enterprise-server@3.XX.
const majorVersion = withoutLanguage.split('/')[1].split('@')[0]
const split = withoutLanguage.split('/')
const version = split[1].split('@')[1]
@@ -181,20 +164,20 @@ export default function getRedirect(uri: string, context: Context): string | und
suffix = tryReplacements(prefix, suffix, context) || suffix
}
} else {
- // If version is not supported, we still need to set these values
+ // Unsupported versions still need prefix and suffix values for the fallback lookup.
prefix = `/${majorVersion}@${version}`
suffix = `/${split.slice(2).join('/')}`
}
const newURL = prefix + suffix
if (newURL !== withoutLanguage) {
- // At least the prefix changed!
+ // Prefix changes can target either a redirect or a live URL.
destination = redirects[newURL] || newURL
} else {
destination = redirects[newURL]
}
} else if (withoutLanguage.startsWith('/desktop/guides/')) {
- // E.g. /desktop/guides/contributing-and-collaborat
+ // Example: /desktop/guides/contributing-and-collaboration
const newURL = withoutLanguage.replace('/desktop/guides/', '/desktop/')
destination = redirects[newURL] || newURL
} else {
@@ -202,8 +185,7 @@ export default function getRedirect(uri: string, context: Context): string | und
}
if (destination !== undefined) {
- // There's hope! Now we just need to attach the correct language
- // to the destination URL.
+ // Redirect destinations need the resolved language prefix.
return `/${language}${destination}`
}
@@ -214,31 +196,26 @@ function githubAERedirect(uri: string, context: Context): string {
const { redirects, userLanguage, pages } = context
if (!redirects || !pages) {
- // Fallback to home page if context is incomplete
+ // Incomplete context cannot choose an equivalent GitHub AE page.
const [language] = splitPathByLanguage(uri, userLanguage)
return `/${language}`
}
const [language, withoutLanguage] = splitPathByLanguage(uri, userLanguage)
- // From now on, github-ae@latest redirects to enterprise-cloud or
- // fpt or the home page.
+ // Try Enterprise Cloud and Free/Pro/Team equivalents before redirect and home-page fallbacks.
const cloudEquivalent = uri.replace('/github-ae@latest', '/enterprise-cloud@latest')
const fptEquivalent = uri.replace('/github-ae@latest', '')
const withoutVersion = withoutLanguage.replace('/github-ae@latest', '')
if (!withoutVersion) {
- // That means the version home page.
- // Don't even need to check if that exists.
- // But if it was without language, inject the language as
- // we go to the enterprise-cloud equivalent
+ // GitHub AE home redirects to Enterprise Cloud without checking pages.
if (uri.startsWith('/github-ae@latest')) {
return `/${language}${cloudEquivalent}`
}
return cloudEquivalent
}
- // What if the only missing thing is a language prefix, then
- // it's easy too.
+ // Language-less GitHub AE URLs can still match a translated equivalent.
if (uri.startsWith('/github-ae@latest')) {
const languageCloudEquivalent = `/${language}${cloudEquivalent}`
if (languageCloudEquivalent in pages) {
@@ -250,7 +227,7 @@ function githubAERedirect(uri: string, context: Context): string {
return languageFptEquivalent
}
} else {
- // If you're here it means the URL did start with a language.
+ // Language-prefixed GitHub AE URLs can check equivalent pages directly.
if (cloudEquivalent in pages) {
return cloudEquivalent
}
@@ -259,8 +236,7 @@ function githubAERedirect(uri: string, context: Context): string {
}
}
- // There are redirect exceptions the specifically spell out github-ae
- // in the redirect.
+ // Exception redirects can point GitHub AE URLs to a non-AE destination.
const legacyRedirect = redirects[withoutLanguage]
if (legacyRedirect && !legacyRedirect.includes('/github-ae@latest')) {
if (legacyRedirect.includes('://')) {
@@ -269,9 +245,7 @@ function githubAERedirect(uri: string, context: Context): string {
return `/${language}${legacyRedirect}`
}
- // The `redirects` are "pure" and don't specific a specific version.
- // For example `/articles/stuff` to `/get-started/new/name`
- // We look for those and try enterprise-cloud in it.
+ // Versionless redirects can still land on Enterprise Cloud or Free/Pro/Team equivalents.
if (redirects[withoutVersion]) {
const cloudCandidate = `/${language}/enterprise-cloud@latest${redirects[withoutVersion]}`
if (cloudCandidate in pages) {
@@ -279,8 +253,7 @@ function githubAERedirect(uri: string, context: Context): string {
}
const fptCandidate = `/${language}${redirects[withoutVersion]}`
- // The lookup of redirects might yield a versioned URL, whose version
- // might be github-ae or enterprise-server. Skip those.
+ // GitHub AE and Enterprise Server candidates would keep the reader on the wrong version.
if (fptCandidate in pages) {
const versionFromCandidate = getVersionStringFromPath(fptCandidate)
if (
@@ -294,16 +267,11 @@ function githubAERedirect(uri: string, context: Context): string {
}
}
- // Note that this includes completely unknown pages
+ // Unknown GitHub AE pages fall back to the localized home page.
return `/${language}`
}
-// Over time, we've developed multiple ambiguous patterns of URLs
-// You can't simply assume that all `/admin/guides` should become
-// `/admin` for example.
-// This function tries different string replacement on the suffix
-// (the pathname after the language and version part) until it
-// finds one string replacement that yields either a page or a redirect.
+// Ambiguous suffixes like /admin/guides need the first replacement that hits a page or redirect.
function tryReplacements(prefix: string, suffix: string, context: Context): string | undefined {
const { pages, redirects } = context
@@ -312,9 +280,7 @@ function tryReplacements(prefix: string, suffix: string, context: Context): stri
}
const test = (testSuffix: string): boolean => {
- // This is a generally broad search and replace and this particular
- // replacement has never been present in api documentation only enterprise
- // admin documentation, so we're excluding the REST api pages
+ // REST API paths are outside the Enterprise Admin replacement patterns.
if (testSuffix.includes('/rest')) {
return false
}
diff --git a/src/redirects/lib/graphql-category-redirect.ts b/src/redirects/lib/graphql-category-redirect.ts
index b31e1365766b..cd31f5578685 100644
--- a/src/redirects/lib/graphql-category-redirect.ts
+++ b/src/redirects/lib/graphql-category-redirect.ts
@@ -1,12 +1,8 @@
-// Dynamic redirect from legacy kind-based GraphQL reference URLs
-// (e.g. `/graphql/reference/scalars#boolean`) to the per-category
-// reference URLs (e.g. `/graphql/reference/other#scalar-boolean`)
-// introduced when docs-internal adopted the upstream `@docsCategory`
-// directive.
+// Redirect legacy kind-based GraphQL reference URLs, such as
+// /graphql/reference/scalars#boolean, to per-category reference URLs, such as
+// /graphql/reference/other#scalar-boolean.
//
-// Resolved in a single hop so the type-name (in the URL fragment) is not
-// lost: fragments are not sent on subsequent requests, so we can't chain a
-// /v4 redirect to a removed kind page and recover the type later.
+// Resolve in one hop because URL fragments are not sent on subsequent requests.
import fs from 'fs'
import path from 'path'
@@ -21,15 +17,15 @@ import {
} from '@/graphql/lib/categories'
import { supported as supportedGhes } from '@/versions/lib/enterprise-server-releases'
-// URL kind segment (e.g. "input-objects") -> internal kind key (e.g. "inputObjects").
+// URL kind segment input-objects maps to internal kind key inputObjects.
const URL_TO_KIND_KEY: Record<string, SchemaKindKey> = Object.fromEntries(
ALL_KIND_KEYS.map((k) => [KIND_URL_SEGMENT[k], k]),
)
-// Set of legacy kind URL segments we redirect from.
+// Accept only these legacy kind segments for redirect parsing.
const LEGACY_KIND_SEGMENTS = new Set(Object.keys(URL_TO_KIND_KEY))
-// Per-version lookup: kind key -> id (lowercased) -> category slug.
+// Per-version lookup maps kind key to lowercased ID to category slug.
type CategoryMap = Partial<Record<SchemaKindKey, Record<string, string>>>
const dataDir = path.join(process.cwd(), 'src/graphql/data')
@@ -48,42 +44,36 @@ function loadCategoryMap(version: string): CategoryMap | null {
return map
}
-// Map URL version segment to a graphql data directory name. Returns null for
-// unsupported / archived versions so the caller can pass them through.
+// Unsupported and archived versions pass through because they have no GraphQL data directory.
function versionUrlToDataDir(versionSegment: string | null): string | null {
if (!versionSegment || versionSegment === 'free-pro-team@latest') return 'fpt'
if (versionSegment === 'enterprise-cloud@latest') return 'ghec'
const m = /^enterprise-server@(\d+\.\d+)$/.exec(versionSegment)
if (m && supportedGhes.includes(m[1])) return `ghes-${m[1]}`
- // enterprise-server@latest also has category data via its current alias,
- // but middleware order means we shouldn't see it here. Pass through.
+ // enterprise-server@latest has category data, but earlier middleware resolves it.
return null
}
const LANGUAGE_RE = new RegExp(`^(${languageKeys.join('|')})$`)
const VERSION_RE = /^(free-pro-team@latest|enterprise-cloud@latest|enterprise-server@[\d.]+)$/
-// Parse a docs URL path into its segments. Returns null if the path is not a
-// graphql-reference legacy kind URL.
+// Parse only legacy GraphQL reference kind URLs.
interface ParsedLegacyUrl {
language: string | null
version: string | null
kindSegment: string
- // Type id (lowercased) parsed from the URL fragment, if any.
+ // Lowercased type ID from the URL fragment, if any.
typeId: string | null
}
function parseLegacyUrl(input: string): ParsedLegacyUrl | null {
- // We accept `redirect` strings that may include a `#fragment` but should not
- // include a query string at this point (callers pass the path-only form).
+ // Callers pass path-only redirects, with optional fragments but no query strings.
const hashIndex = input.indexOf('#')
const pathPart = hashIndex >= 0 ? input.slice(0, hashIndex) : input
const fragment = hashIndex >= 0 ? input.slice(hashIndex + 1) : ''
const segments = pathPart.split('/').filter(Boolean)
- // Expect segments to look like:
- // [<lang>?, <version>?, "graphql", "reference", "<kind>"]
- // with optional language and optional version.
+ // The legacy shape allows optional language and version segments before graphql/reference/kind.
const refIdx = segments.indexOf('reference')
if (refIdx < 0) return null
if (segments[refIdx - 1] !== 'graphql') return null
@@ -92,7 +82,7 @@ function parseLegacyUrl(input: string): ParsedLegacyUrl | null {
const kindSegment = segments[refIdx + 1]
if (!LEGACY_KIND_SEGMENTS.has(kindSegment)) return null
- // The bits before "graphql" can be: nothing, [lang], [version], or [lang, version].
+ // Segments before graphql can be empty, language, version, or language plus version.
const preface = segments.slice(0, refIdx - 1)
let language: string | null = null
let version: string | null = null
@@ -118,13 +108,9 @@ function buildPrefix(language: string | null, version: string | null): string {
return out
}
-// Resolve a legacy URL to its category-based equivalent. Returns null if the
-// input is not a legacy URL or its version is not supported (so callers leave
-// it alone).
+// Resolve legacy type URLs to category pages and bare kind URLs to the reference root.
//
-// `fallbackLanguage` is used when the input URL has no language segment so the
-// rewritten URL is still valid against the language-prefixed `req.context.pages`
-// lookup downstream.
+// fallbackLanguage keeps language-less inputs valid against req.context.pages.
export function applyGraphqlCategoryRedirect(
redirect: string,
fallbackLanguage: string = 'en',
@@ -138,8 +124,7 @@ export function applyGraphqlCategoryRedirect(
const language = parsed.language ?? fallbackLanguage
const prefix = buildPrefix(language, parsed.version)
- // No fragment: legacy bare kind page (e.g. /graphql/reference/scalars). The
- // kind index doesn't exist anymore; send the user to the reference root.
+ // Legacy bare kind pages like /graphql/reference/scalars redirect to the reference root.
if (!parsed.typeId) {
return `${prefix}/graphql/reference`
}
@@ -152,8 +137,7 @@ export function applyGraphqlCategoryRedirect(
return `${prefix}/graphql/reference/${category}#${slugPrefix}-${parsed.typeId}`
}
-// Test-only helper to reset the per-version cache so unit tests can reload
-// fixture maps. Not exported through the public barrel.
+// Tests reset the per-version cache to reload fixture maps without exporting through the barrel.
export function __resetGraphqlCategoryCacheForTests(): void {
lookupCache.clear()
}
diff --git a/src/redirects/lib/permalinks.ts b/src/redirects/lib/permalinks.ts
index 6974dce431b4..00946ac6440e 100644
--- a/src/redirects/lib/permalinks.ts
+++ b/src/redirects/lib/permalinks.ts
@@ -5,6 +5,10 @@ import type { Permalink } from '@/types'
type Redirects = Record<string, string>
+// Versionless redirect fallbacks use the first supported version in lib/all-versions.ts order.
+// Input: /billing/managing-billing-for-your-github-account/managing-invoices-for-your-enterprise
+// Output:
+// /enterprise-cloud@latest/billing/managing-billing-for-your-github-account/managing-invoices-for-your-enterprise
export default function permalinkRedirects(
permalinks: Permalink[],
redirectFrom: string[],
@@ -12,19 +16,12 @@ export default function permalinkRedirects(
const redirects: Redirects = {}
if (!permalinks.length) return redirects
- // The following is handling for versionless redirect fallbacks!
- // We put an entry into `redirects` without any version prefix that goes to the first supported
- // version in the lib/all-versions.ts order. For example, we want this versionless path:
- // /billing/managing-billing-for-your-github-account/managing-invoices-for-your-enterprise
- // to redirect to its first supported version, which is GHEC:
- // /enterprise-cloud@latest/billing/managing-billing-for-your-github-account/managing-invoices-for-your-enterprise
if (permalinks[0].pageVersion !== nonEnterpriseDefaultVersion) {
redirects[getPathWithoutVersion(permalinks[0].hrefWithoutLanguage)] =
permalinks[0].hrefWithoutLanguage
}
- // For every "old" path in a content file's redirect_from frontmatter, also add that path to
- // the redirects object as a key, where the value is the content file's permalink.
+ // redirect_from entries need both versionless and version-prefixed redirect keys.
for (let frontmatterOldPath of redirectFrom) {
if (!frontmatterOldPath.startsWith('/')) {
throw new Error(
@@ -32,23 +29,18 @@ export default function permalinkRedirects(
)
}
- // Exceptions where the `redirect_from` entries are too old
- // Only replace /enterprise/ when it's at the start of the path followed by /admin/
- // This handles legacy patterns like /enterprise/admin/... → /admin/...
- // but preserves paths like /early-access/enterprise/... where enterprise is a directory name
+ // Collapse /admin/guides/ and leading /enterprise/admin/, but preserve nested /enterprise/.
frontmatterOldPath = frontmatterOldPath
.replace('/admin/guides/', '/admin/')
.replace(/^\/enterprise\/admin\//, '/admin/')
for (let index = 0; index < permalinks.length; index++) {
const permalink = permalinks[index]
- // For the first supported permalink (the order is determined by lib/all-versions),
- // put an entry into `redirects` without any version prefix.
+ // Versionless frontmatter redirects use the first supported permalink.
if (index === 0) {
redirects[frontmatterOldPath] = permalink.hrefWithoutLanguage
}
- // For every permalink, put an entry into `redirects` with the version prefix.
redirects[`/${permalink.pageVersion}${frontmatterOldPath}`] = permalink.hrefWithoutLanguage
}
}
diff --git a/src/redirects/lib/precompile.ts b/src/redirects/lib/precompile.ts
index ccd055b194a1..3c74615a4bd9 100644
--- a/src/redirects/lib/precompile.ts
+++ b/src/redirects/lib/precompile.ts
@@ -8,8 +8,7 @@ const EXCEPTIONS_FILE = './src/redirects/lib/static/redirect-exceptions.txt'
type Redirects = Record<string, string>
-// This function runs at server warmup and precompiles possible redirect routes.
-// It outputs them in key-value pairs within a neat JavaScript object: { oldPath: newPath }
+// Server warmup precompiles redirect routes as oldPath to newPath pairs.
export async function precompileRedirects(pageList: Page[]): Promise<Redirects> {
const allRedirects = readCompressedJsonFileFallback(
'./src/redirects/lib/static/developer.json',
@@ -20,47 +19,25 @@ export async function precompileRedirects(pageList: Page[]): Promise<Redirects>
) as Redirects
Object.assign(allRedirects, externalRedirects)
- // create backwards-compatible old paths for page permalinks and frontmatter redirects
+ // Page permalinks and frontmatter redirects need backward-compatible paths.
for (const page of pageList.filter((xpage) => xpage.languageCode === 'en')) {
Object.assign(allRedirects, page.buildRedirects())
}
- // Remove any redirect whose source URL is also a real page permalink.
- // This prevents redirect_from entries from clobbering live pages when a
- // new page (versioned broadly) declares a redirect_from that overlaps
- // with an older page that still exists in some versions.
+ // Live page permalinks win over redirect_from entries that overlap older page versions.
for (const page of pageList.filter((xpage) => xpage.languageCode === 'en')) {
for (const permalink of page.permalinks) {
delete allRedirects[permalink.hrefWithoutLanguage]
}
}
- // NOTE: Exception redirects **MUST COME AFTER** pageList redirects above in order
- // to properly override them. Exception redirects are unicorn one-offs that are not
- // otherwise handled by the versionless redirect fallbacks (see lib/all-versions.ts).
- //
- // Examples of exceptions:
- // * We deprecate the FPT version of a page, and we want the FPT version to redirect
- // to a different version that goes against the order in lib/all-versions.ts.
- // * We deprecate a non-FPT version of a page, and we want the old version to redirect
- // to a different version. Because the order in lib/all-versions.ts only covers
- // versionless links (like `/foo`), we need to specify an exception for the old
- // versioned links (like `/enterprise-cloud@latest/foo`).
- // * We deprecate a version of a page, and instead of falling back to the next
- // available version, we want to redirect that version to a different page entirely.
- //
- // The advantage of the exception redirects file is that it's encoded in plain
- // text so it's possible to write comments and it's also possible to write 1
- // destination URL once for each N redirect origins.
+ // The plain text format keeps one destination URL next to its many redirect origins.
const exceptions = getExceptionRedirects(EXCEPTIONS_FILE) as Redirects
+ // Apply exceptions last so versioned paths override fallback order or target another page.
Object.assign(allRedirects, exceptions)
for (const [fromURI, toURI] of Object.entries(allRedirects)) {
- // If the destination URL has a hardcoded `enterprise-server@latest` in
- // it we need to rewrite that now.
- // We never want to redirect to that as the final URL (in the 301 response)
- // but it might make sense for it to be in the `developer.json`
- // file since that is static.
+ // Static redirects can name enterprise-server@latest, but 301 responses need a real version.
if (toURI.includes('/enterprise-server@latest')) {
allRedirects[fromURI] = toURI.replace(
'/enterprise-server@latest',
diff --git a/src/redirects/lib/version-preference.ts b/src/redirects/lib/version-preference.ts
index 8227879fabd2..c6f089ba1a79 100644
--- a/src/redirects/lib/version-preference.ts
+++ b/src/redirects/lib/version-preference.ts
@@ -2,25 +2,20 @@ import { allVersions, allVersionKeys } from '@/versions/lib/all-versions'
import nonEnterpriseDefaultVersion from '@/versions/lib/non-enterprise-default-version'
import { getPathWithoutLanguage } from '@/frame/lib/path-utils'
-// Every version the reader can actually prefer over the unversioned form.
-// `detect-version.ts` already refuses cookie values outside `allVersionKeys`,
-// so anything reaching here is a real version.
+// detect-version.ts rejects cookie values outside allVersionKeys.
const alternateVersions = allVersionKeys.filter((v) => v !== nonEnterpriseDefaultVersion)
-// Segments that name a version rather than a product, in any form we have ever
-// served. `allVersions` is not enough on its own: it has no key for
-// `enterprise-server@latest`, for deprecated releases like `enterprise-server@3.0`,
-// or for the older `/enterprise/3.3/` and `/enterprise-server/3.9/` shapes. Those
-// still have to count as an explicit request, because a URL naming a version must
-// beat the cookie even when we no longer publish that version.
+// Explicit version URLs must beat the cookie. allVersions omits enterprise-server@latest,
+// deprecated releases like enterprise-server@3.0, and legacy shapes like /enterprise/3.3/
+// and /enterprise-server/3.9/.
const VERSION_PLANS = new Set([
...Object.values(allVersions).map((v) => v.plan),
'github-ae',
'enterprise',
])
-// Does this path name a version itself, rather than leaving it implied?
-// Anything with an `@` is a version segment, because no article slug contains one.
+// A path naming a version beats the cookie.
+// Anything with @ is a version segment, because article slugs do not contain it.
// The plan names cover the legacy unsuffixed shapes.
export function pathNamesAVersion(path: string): boolean {
const firstSegment = getPathWithoutLanguage(path).split('/')[1]
@@ -29,32 +24,23 @@ export function pathNamesAVersion(path: string): boolean {
}
export type VersionPreference = {
- // True when some version cookie value would have changed the response, so the
- // response has to vary on `x-user-version` even when this particular reader has
- // no cookie. Varying only for cookie holders would let a no-cookie reader's
- // cached page be served to someone who should have been redirected.
+ // True when any cookie could change the response, even when this reader has none.
+ // Without this Vary, caches can serve a no-cookie response to a reader who needs a redirect.
vary: boolean
- // Where to send this reader, if their preference applies and the article exists there.
+ // Preference destination, when the article exists there.
redirectTo?: string
}
const NOTHING: VersionPreference = { vary: false }
-// Work out whether a reader's version preference applies to a request.
+// A version cookie behaves like language: it is only the default.
//
-// The rule, decided in github/technical-content#7227, is that version behaves exactly
-// like language: the cookie is only a default, a version named in the URL always wins,
-// and an article that does not exist in the preferred version silently stays put.
+// A version named in the URL wins, and missing preferred-version articles stay put.
//
-// `requestPath` is the URL as asked for, and is what decides whether a version was
-// named. It has to be, because `getRedirect` strips an explicit `/free-pro-team@latest`
-// prefix before we get here. Reading the resolved path instead would make an explicit
-// request for Free/Pro/Team indistinguishable from no request at all, and a reader who
-// has set a cookie could never deliberately look at the Free/Pro/Team article again.
+// requestPath decides whether the URL named a version because getRedirect strips an
+// explicit /free-pro-team@latest prefix before this point.
//
-// `resolvedPath` is where the ordinary redirect logic decided to send them, and is what
-// the versioned candidate is built from, so a renamed article resolves in one hop
-// instead of two.
+// resolvedPath builds the versioned candidate so renamed articles resolve in one hop.
export function getVersionPreference(
requestPath: string,
resolvedPath: string,
@@ -66,15 +52,11 @@ export function getVersionPreference(
if (pathNamesAVersion(requestPath) || pathNamesAVersion(resolvedPath)) return NOTHING
- // Always a `URL.pathname` from the caller, so it always starts with `/` and this is
- // always the first segment. On a path that never got a language prefix this reads some
- // article slug as the language, and the candidate lookup below simply misses, because
- // every key in `pages` is language-prefixed.
+ // Language-less paths read a slug as the language and miss the language-prefixed pages lookup.
const language = resolvedPath.split('/')[1]
const withoutLanguage = getPathWithoutLanguage(resolvedPath)
- // `pages` is keyed by permalink, which carries no `.md` extension. Keep the extension
- // aside so a `.md` request redirects to the `.md` form of the versioned article.
+ // pages keys omit .md, but .md requests must redirect to .md versioned articles.
const extension = withoutLanguage.endsWith('.md') ? '.md' : ''
const lookupSuffix = extension ? withoutLanguage.slice(0, -extension.length) : withoutLanguage
@@ -83,8 +65,7 @@ export function getVersionPreference(
for (const version of alternateVersions) {
if (!(`/${language}/${version}${lookupSuffix}` in pages)) continue
- // At least one version of this article exists that the cookie could select, so the
- // response depends on the cookie whether or not this reader has one.
+ // Any selectable version makes the response depend on x-user-version.
vary = true
if (version === userVersion) {
redirectTo = `/${language}/${version}${lookupSuffix}${extension}`
diff --git a/src/redirects/middleware/handle-redirects.ts b/src/redirects/middleware/handle-redirects.ts
index d1e0d0d58427..0b25be9fb03c 100644
--- a/src/redirects/middleware/handle-redirects.ts
+++ b/src/redirects/middleware/handle-redirects.ts
@@ -13,21 +13,26 @@ import {
} from '@/frame/middleware/cache-control'
import { ExtendedRequest, URLSearchParamsTypes } from '@/types'
+// Version preference redirects stay in their own branch so cookie-dependent paths use 302.
+// A 301 would cache one reader's version preference in the browser.
+// Deep links from search, the product UI, or bookmarks otherwise ignore the cookie and serve
+// Free/Pro/Team. Measured corrective switching showed 1,288 moves to Enterprise Cloud and 500
+// moves to Enterprise Server per 24 hours.
+// When getVersionPreference returns vary without redirectTo, append Vary: x-user-version,
+// because the 200 response depends on the cookie.
+// Use append, not set, to keep existing Vary values.
+// src/versions/tests/version-cookie.ts verifies the served header.
export default function handleRedirects(req: ExtendedRequest, res: Response, next: NextFunction) {
if (!req.context) throw new Error('Request not contextualized')
- // Any double-slashes in the URL should be removed first
- // This must be done before checking if the path
- // is an asset (patterns.assetPaths)
+ // Collapse duplicate slashes before patterns.assetPaths, so //example.com cannot bypass handling.
if (req.path.includes('//')) {
return res.safeRedirect(301, req.path.replace(/\/+/g, '/'))
}
- // never redirect assets
if (patterns.assetPaths.test(req.path)) return next()
- // All /api/ endpoints handle their own redirects
- // such as /api/pageinfo redirects to /api/pageinfo/v1
+ // API endpoints handle their own redirects.
if (req.path.startsWith('/api/')) return next()
if (req.path === '/') {
@@ -50,12 +55,7 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
let redirect = req.path
let queryParams = req.originalUrl.includes('?') ? req.originalUrl.split('?')[1] : null
- // Redirect `/some/uri?q=stuff` to `/en/search?query=stuff`
- // Redirect `/some/uri?query=stuff` to `/en/search?query=stuff`
- // Redirect `/fr/version@latest/some/uri?query=stuff`
- // to `/fr/version@latest/search?query=stuff`
- // The `q` param is deprecated, but we still need to support it in case
- // there are links out there that use it.
+ // Route page searches to the search endpoint, and rename legacy q to query.
const onSearch = req.path.endsWith('/search') || req.path.startsWith('/api/search')
const hasQ = 'q' in req.query
const hasQuery = 'query' in req.query
@@ -71,9 +71,7 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
const { currentVersion } = req.context
if (currentVersion !== 'free-pro-team@latest') {
redirectTo += `/${currentVersion}`
- // The `req.context.currentVersion` is just the portion of the URL
- // pathname. It could be that the currentVersion is something
- // like `enterprise` which needs to be redirected to its new name.
+ // currentVersion comes from the path, so legacy names such as enterprise need getRedirect.
redirectTo = getRedirect(redirectTo, req.context) || redirectTo
}
@@ -81,21 +79,18 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
return res.safeRedirect(301, redirectTo)
}
- // have to do this now because searchPath replacement changes the path as well as the query params
if (queryParams) {
queryParams = `?${queryParams}`
}
- // remove query params temporarily so we can find the path in the redirects object
+ // Redirect keys omit query strings.
let redirectWithoutQueryParams = removeQueryParams(redirect)
const redirectTo = getRedirect(redirectWithoutQueryParams, req.context)
redirectWithoutQueryParams = redirectTo || redirectWithoutQueryParams
- // Resolve legacy `/graphql/reference/<kind>(#<name>)?` URLs to their
- // per-category equivalent. Done before query-param re-application so the
- // fragment parsing in the helper is unambiguous.
+ // Parse legacy GraphQL fragments before reapplying query params, so fragment parsing stays clear.
const graphqlRewrite = applyGraphqlCategoryRedirect(
redirectWithoutQueryParams,
req.context.userLanguage || 'en',
@@ -107,16 +102,9 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
redirect = queryParams ? redirectWithoutQueryParams + queryParams : redirectWithoutQueryParams
if (!redirectTo && !pathLanguagePrefixed(req.path)) {
- // No redirect necessary, but perhaps it's to a known page, and the URL
- // currently doesn't have a language prefix, then we need to add
- // the language prefix.
- // We can't always force on the language prefix because some URLs
- // aren't pages. They're other middleware endpoints such as
- // `/healthcheck` which should never redirect.
- // But for example, a `/authentication/connecting-to-github-with-ssh`
- // needs to become `/en/authentication/connecting-to-github-with-ssh`
+ // Add a language prefix only for pages or deprecated versions; /healthcheck passes through.
const possibleRedirectTo = `/en${req.path}`
- // Pages are keyed without .md, so strip it before lookup
+ // Pages are keyed without .md, so strip the extension before lookup.
const lookupPath = possibleRedirectTo.endsWith('.md')
? possibleRedirectTo.replace(/\.md$/, '')
: possibleRedirectTo
@@ -124,25 +112,13 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
if (lookupPath in req.context.pages || isDeprecatedVersion(req.path)) {
const language = getLanguage(req)
- // Note, it's important to use `req.url` here and not `req.path`
- // because the full URL can contain query strings.
- // E.g. `/foo?json=breadcrumbs`
+ // Use req.url here so redirects preserve query strings such as ?json=breadcrumbs.
redirect = `/${language}${req.url}`
}
}
if (!req.context.pages) throw new Error('req.context.pages not yet set')
- // Honor the reader's version preference on a URL that does not name a version.
- //
- // Without this, the cookie is only ever consulted on the bare homepage, so a deep link
- // from search, the product UI, or a bookmark silently serves Free/Pro/Team. See
- // github/technical-content#7227 for the measurements.
- //
- // This is deliberately its own branch rather than a tweak to `redirect` below, because
- // the ordinary path would emit a 301 for a language-prefixed URL. A redirect that
- // depends on a cookie has to stay a 302, or a browser caches one reader's preference
- // forever.
if (!redirect.includes('://')) {
const preference = getVersionPreference(
req.path,
@@ -151,18 +127,6 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
req.context.pages,
)
if (preference.vary && !preference.redirectTo) {
- // Only needed when we do not redirect. The redirect below calls
- // `languageAndVersionCacheControl`, which already lists `x-user-version`.
- //
- // We set it even though this response is not a redirect, because it still depends
- // on the cookie: a cached copy without this header would be served to readers whose
- // preference we should have honored.
- //
- // `append`, not `set`, so this survives the cache-control call that whatever
- // handles the request downstream makes. Those all append too, so nothing clobbers
- // it. The `varies on the cookie even for readers who have not set one` test in
- // `src/versions/tests/version-cookie.ts` asserts the served 200 really does carry
- // the header, so this holds even if that stops being true.
res.append('vary', 'x-user-version')
}
if (preference.redirectTo) {
@@ -175,7 +139,7 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
return next()
}
- // do not redirect if the redirected page can't be found
+ // Skip internal redirects whose target page is missing.
if (
!(
req.context.pages[removeQueryParams(redirect).replace(/\.md$/, '')] ||
@@ -183,15 +147,14 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
) &&
!redirect.includes('://')
) {
- // display error on the page in development, but not in production
- // include final full redirect path in the message
+ // Development responses expose the missing redirect target; production keeps the page clean.
if (process.env.NODE_ENV !== 'production' && req.context) {
req.context.redirectNotFound = redirect
}
return next()
}
- // do the redirect if the from-URL already had a language in it
+ // Language-prefixed and external redirects do not vary by language preference.
if (pathLanguagePrefixed(req.path) || redirect.includes('://')) {
defaultCacheControl(res)
} else {
@@ -203,27 +166,17 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
}
function getLanguage(req: ExtendedRequest, default_ = 'en') {
- // req.context.userLanguage, if it truthy, is always a valid supported
- // language. It's whatever was in the user's request in lib/languages.ts
+ // detect-language.ts limits userLanguage to supported cookie or Accept-Language values.
return req.context!.userLanguage || default_
}
function usePermanentRedirect(req: ExtendedRequest) {
- // If the redirect was to essentially swap `enterprise-server@latest`
- // for `enterprise-server@3.x` then, we definitely don't want to
- // do a permanent redirect.
- // When this is the case, we don't want a permanent redirect because
- // it could overzealously cache in the users' browser which could
- // be bad when whatever "latest" means changes.
+ // Redirects from enterprise-server@latest stay temporary because latest changes over time.
if (req.path.includes('/enterprise-server@latest')) return false
- // If the redirect involved injecting a language prefix, then don't
- // permanently redirect because that could overly cache in users'
- // browsers if we some day want to make the language redirect
- // depend on a cookie or 'Accept-Language' header.
+ // Language-prefixed paths redirect permanently here; injected prefixes fall through to temporary.
if (pathLanguagePrefixed(req.path)) return true
- // The default is to *not* do a permanent redirect.
return false
}
@@ -231,13 +184,10 @@ function removeQueryParams(redirect: string) {
return new URL(redirect, 'https://docs.github.com').pathname
}
+// Deprecated enterprise-server releases in deprecatedWithFunctionalRedirects have functional
+// redirects but no lookup entries or active req.context.pages for custom Next.js paths such as
+// /admin/release-notes.
function isDeprecatedVersion(path: string) {
- // When we rewrote how redirects work, from a lookup model to a
- // functional model, the enterprise-server releases that got
- // deprecated since then fall between the cracks. Especially
- // for custom NextJS page-like pages like /admin/release-notes
- // These URLs don't come from any remaining .json lookup file
- // and they're not active pages either (e.g. req.context.pages)
const split = path.split('/')
for (const version of deprecatedWithFunctionalRedirects) {
if (split.includes(`enterprise-server@${version}`)) {
diff --git a/src/redirects/middleware/language-code-redirects.ts b/src/redirects/middleware/language-code-redirects.ts
index d4561c734497..57fc324efffb 100644
--- a/src/redirects/middleware/language-code-redirects.ts
+++ b/src/redirects/middleware/language-code-redirects.ts
@@ -7,9 +7,7 @@ import { ExtendedRequest } from '@/types'
const redirectPatterns = Object.values(languages)
.map((language) => language.redirectPatterns || [])
.flat()
-// If the enabled languages have `.redirectPatterns`, combine them
-// into one which we only need to use to determine if we should bother
-// doing the redirect at all.
+// Combine enabled language redirectPatterns for a cheap precheck before scanning every pattern.
const combinedRedirectPatternRegex =
redirectPatterns.length > 0
? new RegExp(redirectPatterns.map((rex) => rex.source).join('|'))
@@ -19,26 +17,20 @@ const allRedirectPatterns = Object.values(languages)
.map((language) =>
(language.redirectPatterns || []).map((redirectPattern) => [language.code, redirectPattern]),
)
- .flat() as [string, RegExp][] // Seems TypeScript didn't understand the .flat()
+ .flat() as [string, RegExp][] // flat() loses tuple type inference.
-// This middleware handles redirects for mistyped language codes
-//
-// Examples:
-// /jp* -> /ja*
-// /zh-TW* -> /zh*
+// Redirect mistyped language codes, for example /jp* -> /ja* and /zh-TW* -> /zh*.
export default function languageCodeRedirects(
req: ExtendedRequest,
res: Response,
next: NextFunction,
) {
- // Only in the unlikely event that the `req.path` starts with one of these
- // prefixes do we bother looking up what the redirect should be.
+ // Only paths matching the combined precheck need per-language pattern lookup.
if (req.path.startsWith('/_next/static')) return next()
if (!combinedRedirectPatternRegex) return next()
if (!combinedRedirectPatternRegex.test(req.path)) return next()
- // This loop is almost never ever used so it doesn't have to be
- // particularly smart or fast.
+ // This rare path favors clarity over optimizing the pattern scan.
const matched = allRedirectPatterns.find(([, pattern]) => pattern.test(req.path))
if (matched) {
const [code, pattern] = matched
diff --git a/src/redirects/scripts/get-new-dotcom-path.ts b/src/redirects/scripts/get-new-dotcom-path.ts
index 57c87016b571..89ce2a21c208 100644
--- a/src/redirects/scripts/get-new-dotcom-path.ts
+++ b/src/redirects/scripts/get-new-dotcom-path.ts
@@ -1,9 +1,5 @@
-// [start-readme]
-//
-// Pass this script any old dotcom path (e.g., `articles/foo` or `foo.md`) and it
-// will output the new path in the content/github directory.
-//
-// [end-readme]
+// Finds the content/github path for an old dotcom path.
+// content/github no longer exists, so this script currently fails.
import assert from 'assert'
import { last } from 'lodash-es'
@@ -22,7 +18,6 @@ let filename: string = oldPath
if (filename.includes('/')) filename = last(filename.split('/')) as string
-// first check whether name is a category
const categoryDir = `${newDotcomDir}/${filename.replace(markdownRegex, '')}`
if (fs.existsSync(categoryDir)) {
@@ -30,7 +25,6 @@ if (fs.existsSync(categoryDir)) {
process.exit(0)
}
-// otherwise add extension and check whether it's a file
if (!filename.endsWith(markdownExtension)) filename = filename + markdownExtension
const newPath: string = execSync(`find ${newDotcomDir} -name ${filename}`).toString()
diff --git a/src/redirects/tests/content/redirect-orphans.ts b/src/redirects/tests/content/redirect-orphans.ts
index 5219ede4c86c..c975fa64181a 100644
--- a/src/redirects/tests/content/redirect-orphans.ts
+++ b/src/redirects/tests/content/redirect-orphans.ts
@@ -5,12 +5,11 @@ import { describe, expect, test, vi } from 'vitest'
import { loadPages } from '@/frame/lib/page-data'
describe('redirect orphans', () => {
- // Because calling `loadPages` will trigger a warmup, this can potentially
- // be very slow in CI. So we need a timeout.
+ // loadPages warms up the page cache, which can be slow in CI, so this test needs a timeout.
vi.setConfig({ testTimeout: 60 * 1000 })
test('no redirect_from entry has a trailing slash', async () => {
- // Only doing English because they're the only files we do PRs for.
+ // Only English files receive pull requests, so test English redirect_from entries.
const pageList = await loadPages(undefined, ['en'])
const errors = []
diff --git a/src/redirects/tests/ghae.ts b/src/redirects/tests/ghae.ts
index 300931301887..da17f2875475 100644
--- a/src/redirects/tests/ghae.ts
+++ b/src/redirects/tests/ghae.ts
@@ -1,9 +1,5 @@
-// We entirely removed GHAE but we still have to support legacy links.
-// The unit tests cover `getRedirect()` directly. These are end-to-end tests
-// that span the middleware, which uses `getRedirect()` internally.
-//
-// They matter because ghae is gone from the `allVersions` config object, so
-// these redirects are all that is left of it.
+// GitHub AE legacy links redirect through middleware; github-ae is absent from allVersions.
+// These end-to-end tests cover the middleware path; unit tests cover getRedirect directly.
import { describe, expect, test } from 'vitest'
@@ -31,7 +27,7 @@ describe('ghae redirects', () => {
test('ghae release notes', async () => {
const res = await head('/en/github-ae@latest/admin/release-notes')
expect(res.statusCode).toBe(301)
- // There is not an "equivalent" release notes page for enterprise-cloud
+ // No enterprise-cloud release notes equivalent exists.
expect(res.headers.location).toMatch('/en')
})
})
diff --git a/src/redirects/tests/redirects.ts b/src/redirects/tests/redirects.ts
index 93d5ebc52eae..138303aeb376 100644
--- a/src/redirects/tests/redirects.ts
+++ b/src/redirects/tests/redirects.ts
@@ -67,8 +67,7 @@ describe('redirects', () => {
})
test('have faq= not converted to query=', async () => {
- // Don't confuse `?faq=` for `?q=` just because they both start with `q=`
- // Docs internal #21945
+ // Keep faq intact while q becomes query.
const res = await get('/en/enterprise/admin?faq=pulls')
expect(res.statusCode).toBe(301)
const expected = `/en/enterprise-server@${enterpriseServerReleases.latest}/admin?faq=pulls`
@@ -115,7 +114,7 @@ describe('redirects', () => {
const res = await get('/')
expect(res.statusCode).toBe(302)
expect(res.headers.location).toBe('/en')
- // language specific caching
+ // Language redirects vary by language preference.
expect(res.headers['cache-control']).toContain('public')
expect(res.headers['cache-control']).toMatch(/max-age=\d+/)
expect(res.headers.vary).toContain('accept-language')
@@ -222,15 +221,12 @@ describe('redirects', () => {
test('frontmatter redirect', async () => {
const res = await get('/enterprise/2.12/user/articles/github-flavored-markdown')
- expect(res.statusCode).toBe(302) // because it doesn't have a language
+ expect(res.statusCode).toBe(302) // Missing language keeps this redirect temporary.
expect(res.headers.location).toBe('/enterprise/2.12/user/categories/writing-on-github/')
})
})
describe('enterprise admin', () => {
- // firstRestoredAdminGuides = 2.21
- // lastBeforeRestoredAdminGuides = 2.20
- // (these won't change but it's more convenient to use constants)
const { firstRestoredAdminGuides, getPreviousReleaseNumber, latest } = enterpriseServerReleases
const lastBeforeRestoredAdminGuides = getPreviousReleaseNumber(firstRestoredAdminGuides)
const enterpriseAdmin = `/en/enterprise-server@${latest}/admin`
@@ -321,7 +317,7 @@ describe('redirects', () => {
expect(res.headers.location).toBe(userArticle)
})
- // 2.16 was the first version where we moved /articles/foo to /github/<category>/foo
+ // Enterprise 2.16 is the redirect boundary for /articles/foo to /github/<category>/foo.
test('no product does not redirect to GitHub.com product in <=2.15', async () => {
const res = await get('/en/enterprise/2.15/user/articles/set-up-git')
expect(res.statusCode).toBe(200)
@@ -427,7 +423,7 @@ describe('redirects', () => {
test('no domain redirect on //example.com/', async () => {
const res = await get(`//example.com/`)
expect(res.statusCode).toBe(301)
- expect(res.headers.location).toBe(`/example.com`) // should not be //example.com
+ expect(res.headers.location).toBe(`/example.com`) // Guards against //example.com.
const res2 = await get(res.headers.location)
expect(res2.statusCode).toBe(404)
})
diff --git a/src/redirects/tests/routing/developer-site-redirects.ts b/src/redirects/tests/routing/developer-site-redirects.ts
index a3e6d6e9bbb8..dd8d4cdb113b 100644
--- a/src/redirects/tests/routing/developer-site-redirects.ts
+++ b/src/redirects/tests/routing/developer-site-redirects.ts
@@ -10,9 +10,7 @@ describe('developer redirects', () => {
vi.setConfig({ testTimeout: 60 * 1000 })
beforeAll(async () => {
- // The first page load takes a long time so let's get it out of the way in
- // advance to call out that problem specifically rather than misleadingly
- // attributing it to the first test
+ // Warm up the first page load so later failures point to the redirect under test.
await get('/v4')
})
@@ -70,27 +68,23 @@ describe('developer redirects', () => {
expectedFinalPath = '/en/rest'
expect(res.headers.location).toBe(expectedFinalPath)
- // REST subresources like activity notifications don't have their own page
- // anymore, so redirect to an anchor on the resource page
+ // REST subresource paths like activity notifications resolve under the resource page.
res = await get('/en/v3/activity')
expect(res.statusCode).toBe(301)
expectedFinalPath = '/en/rest/activity'
expect(res.headers.location).toBe(expectedFinalPath)
- // REST subresources like activity notifications don't have their own page
- // anymore, so redirect to an anchor on the resource page
+ // REST subresource paths like activity notifications resolve under the resource page.
res = await get('/en/v3/activity/notifications')
expect(res.statusCode).toBe(301)
expectedFinalPath = '/en/rest/activity/notifications'
expect(res.headers.location).toBe(expectedFinalPath)
- // trailing slashes are handled separately by the `slashes` module;
- // any request to a /v3 URL with a trailing slash will be redirected twice
+ // The slashes middleware removes trailing slash first, causing two redirects for /v3 URLs.
res = await get('/en/v3/activity/notifications/')
expect(res.statusCode).toBe(301)
expect(res.headers.location).toBe('/en/v3/activity/notifications')
- // non-reference redirects (e.g. guides)
res = await get('/en/v3/guides/basics-of-authentication')
expect(res.statusCode).toBe(301)
expectedFinalPath =
@@ -107,11 +101,9 @@ describe('developer redirects', () => {
}
if (!(label in FIXTURES)) throw new Error('unrecognized label')
const fixtures = readJsonFile(FIXTURES[label as keyof typeof FIXTURES])
- // Don't use a `Promise.all()` because it's actually slower
- // because of all the eventloop context switching.
+ // Avoid Promise.all here; event loop context switching makes it slower.
for (let [oldPath, newPath] of Object.entries(fixtures as Record<string, string>)) {
- // REST and GraphQL developer Enterprise paths with a version are only supported up to 2.21.
- // We make an exception to always redirect versionless paths to the latest version.
+ // Versioned developer Enterprise paths support up to 2.21; versionless paths use latest.
newPath = (newPath as string).replace(
'/enterprise-server/',
`/enterprise-server@${enterpriseServerReleases.latest}/`,
diff --git a/src/redirects/tests/routing/versionless-redirects.ts b/src/redirects/tests/routing/versionless-redirects.ts
index 6b62bc92f518..56cc1fb0b313 100644
--- a/src/redirects/tests/routing/versionless-redirects.ts
+++ b/src/redirects/tests/routing/versionless-redirects.ts
@@ -12,9 +12,8 @@ const VERSIONLESS_REDIRECTS_FILE = path.join(
'../../../../src/fixtures/fixtures/versionless-redirects.txt',
)
-// This test checks the default versioning redirect fallbacks described in lib/all-versions.ts.
-// The fixture now contains mock URLs instead of live URLs to prevent test failures when content is moved.
-// This ensures the redirect logic works correctly without being dependent on real content files.
+// These tests cover default versioning redirect fallbacks from lib/all-versions.ts.
+// The fixture uses mock URLs, so moved content cannot break them.
describe('versioned redirects', () => {
vi.setConfig({ testTimeout: 60 * 1000 })
diff --git a/src/redirects/tests/unit/get-redirect.ts b/src/redirects/tests/unit/get-redirect.ts
index 07a94b790293..25ce8fca5b1e 100644
--- a/src/redirects/tests/unit/get-redirect.ts
+++ b/src/redirects/tests/unit/get-redirect.ts
@@ -18,13 +18,9 @@ type TestContext = {
const previousEnterpriserServerVersion = supported[1]
describe('getRedirect basics', () => {
+ // Static developer.json redirects must win before legacy enterprise prefixes are normalized.
+ // For /enterprise/3.0/foo/bar, lookup happens before /enterprise-server@3.0 rewriting.
test('should sometimes not correct the version prefix', () => {
- // This essentially tests legacy entries that come from the
- // `developer.json` file. Normally, we would have first
- // rewritten `/enterprise/3.0` to `/enterprise-server@3.0`
- // and then, from there, worried about the remaining `/foo/bar`
- // part.
- // But some redirects from `developer.json` as old and static.
const uri = '/enterprise/3.0/foo/bar'
const ctx: TestContext = {
pages: {},
@@ -72,7 +68,7 @@ describe('getRedirect basics', () => {
},
}
expect(getRedirect('/free-pro-team@latest', ctx as unknown as Context)).toBe('/en')
- // Language is fine, but the version needs to be "removed"
+ // free-pro-team@latest is versionless, so the language prefix remains.
expect(getRedirect('/en/free-pro-team@latest', ctx as unknown as Context)).toBe('/en')
expect(getRedirect('/free-pro-team@latest/pizza', ctx as unknown as Context)).toBe('/en/pizza')
expect(getRedirect('/free-pro-team@latest/foo', ctx as unknown as Context)).toBe('/en/bar')
@@ -108,7 +104,7 @@ describe('getRedirect basics', () => {
},
redirects: {},
}
- // Replacing `/user` with `` worked because there exits a page of such name.
+ // The /user prefix can drop because the resulting page exists.
expect(
getRedirect(
`/enterprise-server@${previousEnterpriserServerVersion}/user/foo/bar`,
@@ -142,12 +138,12 @@ describe('getRedirect basics', () => {
ctx as unknown as Context,
),
).toBe(`/en/enterprise-server@${previousEnterpriserServerVersion}/something`)
- // but also respect redirects if there are some
+ // Respect redirects after normalizing the old enterprise prefix.
expect(
getRedirect(`/enterprise/${previousEnterpriserServerVersion}/foo`, ctx as unknown as Context),
).toBe(`/en/enterprise-server@${previousEnterpriserServerVersion}/bar`)
- // Unique snowflake pattern
+ // /enterprise/github paths map to enterprise-server github/admin paths.
expect(getRedirect('/enterprise/github/admin/foo', ctx as unknown as Context)).toBe(
`/en/enterprise-server@${latest}/github/admin/foo`,
)
@@ -158,8 +154,7 @@ describe('getRedirect basics', () => {
pages: {},
redirects: {},
}
- // Nothing's needed here because it's not /admin/guides and
- // it already has the enterprise-server prefix.
+ // No admin/guides rewrite applies when the path already has enterprise-server.
expect(
getRedirect(
`/en/enterprise-server@${latest}/admin/something/else`,
@@ -179,16 +174,14 @@ describe('getRedirect basics', () => {
[`/enterprise-server@${latestStable}/foo`]: `/enterprise-server@${latestStable}/bar`,
},
}
- // Nothing's needed here because it's not /admin/guides and
- // it already has the enterprise-server prefix.
+ // enterprise-server without a version resolves to latest stable before redirect lookup.
expect(getRedirect('/enterprise-server/foo', ctx as unknown as Context)).toBe(
`/en/enterprise-server@${latestStable}/bar`,
)
})
+ // Functional redirects cover enterprise-server 3.0 and later without lookup entries.
test('should work for some deprecated enterprise-server URLs too', () => {
- // Starting with enterprise-server 3.0, we have made redirects become
- // a *function* rather than a lookup on a massive object.
const ctx: TestContext = {
pages: {},
redirects: {},
@@ -282,7 +275,7 @@ describe('github-ae@latest', () => {
const ctx: TestContext = {
pages: {
'/en/foo': true,
- // Note the lack of an enterprise-cloud page here
+ // No enterprise-cloud page exists here, so GitHub AE falls back to Free/Pro/Team.
},
redirects: {
'/food': '/foo',
diff --git a/src/redirects/tests/unit/graphql-category-redirect.ts b/src/redirects/tests/unit/graphql-category-redirect.ts
index 670cd93cd333..58d09d9333ea 100644
--- a/src/redirects/tests/unit/graphql-category-redirect.ts
+++ b/src/redirects/tests/unit/graphql-category-redirect.ts
@@ -11,8 +11,7 @@ describe('applyGraphqlCategoryRedirect', () => {
})
test('rewrites a legacy scalar URL with language prefix', () => {
- // Boolean is a built-in GraphQL scalar with no @docsCategory, so it falls
- // to the `other` bucket.
+ // Built-in GraphQL scalars have no @docsCategory, so they fall into the other bucket.
expect(applyGraphqlCategoryRedirect('/en/graphql/reference/scalars#boolean')).toBe(
'/en/graphql/reference/other#scalar-boolean',
)
@@ -31,7 +30,7 @@ describe('applyGraphqlCategoryRedirect', () => {
})
test('uses the category from the schema map when annotated', () => {
- // `Repository` is annotated with `@docsCategory(name: "repos")` upstream.
+ // Repository has @docsCategory(name: "repos") in the upstream schema.
expect(applyGraphqlCategoryRedirect('/en/graphql/reference/objects#repository')).toBe(
'/en/graphql/reference/repos#object-repository',
)
@@ -44,7 +43,7 @@ describe('applyGraphqlCategoryRedirect', () => {
})
test('handles `input-objects` kind segment', () => {
- // CustomPropertyValueInput is categorized as `repos` in the fpt schema.
+ // The fpt schema categorizes CustomPropertyValueInput as repos.
expect(
applyGraphqlCategoryRedirect('/en/graphql/reference/input-objects#custompropertyvalueinput'),
).toBe('/en/graphql/reference/repos#input-object-custompropertyvalueinput')
diff --git a/src/redirects/tests/unit/precompile.ts b/src/redirects/tests/unit/precompile.ts
index e702ee09205e..b4d884c9b708 100644
--- a/src/redirects/tests/unit/precompile.ts
+++ b/src/redirects/tests/unit/precompile.ts
@@ -13,8 +13,8 @@ vi.mock('../../lib/exception-redirects', () => ({
const { default: precompileRedirects } = await import('../../lib/precompile')
const { default: generateRedirectsForPermalinks } = await import('../../lib/permalinks')
-// Minimal stand-in for a Page instance. precompileRedirects() only relies on
-// `languageCode`, `permalinks`, and `buildRedirects()`.
+// makePage supplies only the Page fields precompileRedirects needs: languageCode, permalinks, and
+// buildRedirects.
function makePage(
languageCode: string,
permalinks: { pageVersion: string; hrefWithoutLanguage: string }[],
@@ -36,7 +36,7 @@ function makePage(
describe('precompileRedirects', () => {
test('removes a redirect_from-generated redirect that clobbers a live old-page permalink, but keeps it for versions where the old page is absent', async () => {
- // The old page only exists in GHES 3.14.
+ // The old page exists only in GHES 3.14.
const oldPage = makePage(
'en',
[
@@ -48,9 +48,7 @@ describe('precompileRedirects', () => {
[],
)
- // The replacement page exists in both 3.14 and 3.15, and declares
- // `redirect_from: ['/foo']`, which would otherwise clobber the old
- // page's live permalink in 3.14.
+ // redirect_from on the replacement page must not clobber the old GHES 3.14 permalink.
const newPage = makePage(
'en',
[
@@ -68,12 +66,10 @@ describe('precompileRedirects', () => {
const redirects = await precompileRedirects([oldPage, newPage])
- // The old page's live permalink in 3.14 must not be clobbered by the
- // replacement page's redirect_from.
+ // The GHES 3.14 old-page permalink wins over the replacement page's redirect_from.
expect(redirects['/enterprise-server@3.14/foo']).toBeUndefined()
- // But in 3.15, where the old page doesn't exist, the redirect must
- // still be there.
+ // GHES 3.15 lacks the old page, so redirect_from still creates the redirect.
expect(redirects['/enterprise-server@3.15/foo']).toBe('/enterprise-server@3.15/bar')
})
})
diff --git a/src/redirects/tests/version-preference.ts b/src/redirects/tests/version-preference.ts
index f6a9e6a53bfa..f9c27ae37b57 100644
--- a/src/redirects/tests/version-preference.ts
+++ b/src/redirects/tests/version-preference.ts
@@ -6,9 +6,8 @@ import { latest } from '@/versions/lib/enterprise-server-releases'
const GHEC = 'enterprise-cloud@latest'
const GHES = `enterprise-server@${latest}`
-// A stand-in for `req.context.pages`, which is keyed by full versioned permalink.
-// `/actions/versioned` exists in all three versions, `/actions/fpt-only` only in the
-// unversioned one.
+// pages stands in for req.context.pages, keyed by full versioned permalink.
+// /actions/versioned exists in all three versions; /actions/fpt-only exists only unversioned.
const pages = Object.fromEntries(
[
'/en/actions/versioned',
@@ -27,14 +26,13 @@ describe('pathNamesAVersion', () => {
['/en/enterprise-cloud@latest/actions/foo', true],
['/en/free-pro-team@latest/actions/foo', true],
['/en/enterprise-server@latest/actions/foo', true],
- // Deprecated releases are not keys of `allVersions`, but naming one is still
- // an explicit request and has to beat the cookie.
+ // Deprecated releases are absent from allVersions, but explicit version paths beat the cookie.
['/en/enterprise-server@3.0/actions/foo', true],
['/en/github-ae@latest/actions/foo', true],
- // Legacy shapes that carry no `@`.
+ // Legacy shapes without @ still name a version.
['/en/enterprise-server/3.9/actions/foo', true],
['/en/enterprise/3.3/actions/foo', true],
- // No version named.
+ // These paths name no version.
['/en/actions/foo', false],
['/actions/foo', false],
['/en', false],
@@ -56,9 +54,8 @@ describe('getVersionPreference', () => {
expect(getVersionPreference(path, path, GHEC, pages)).toEqual({ vary: false })
})
- // The escape hatch. `getRedirect` strips `/free-pro-team@latest` before the middleware
- // gets here, so the resolved path looks unversioned. Only the request path still shows
- // that the reader asked for Free/Pro/Team on purpose.
+ // free-pro-team@latest is an escape hatch: getRedirect strips it before this helper runs.
+ // The original request path still proves the reader explicitly asked for Free/Pro/Team.
test('leaves an explicit free-pro-team URL alone even after the prefix is stripped', () => {
expect(
getVersionPreference(
@@ -88,9 +85,8 @@ describe('getVersionPreference', () => {
).toEqual({ vary: true, redirectTo: `/en/${GHES}/actions/versioned` })
})
- // The partial case: this article has a version the cookie could have selected, just not
- // the one this reader asked for. No redirect, but the response still depends on the
- // cookie, so it must not be cached as though it were the same for everyone.
+ // If the cookie names a version the article lacks, the response still depends on the cookie.
+ // Vary prevents caches from serving that fallback response to readers with other preferences.
test('varies without redirecting when the cookie names a version this article lacks', () => {
expect(
getVersionPreference('/en/actions/ghec-only', '/en/actions/ghec-only', GHES, pages),
@@ -139,8 +135,7 @@ describe('getVersionPreference', () => {
})
})
- // The redirect target names a version, so the next request short-circuits on
- // `pathNamesAVersion` and cannot bounce back.
+ // Versioned redirect targets short-circuit on pathNamesAVersion, so they cannot bounce back.
test('cannot loop', () => {
const first = getVersionPreference(
'/en/actions/versioned',
diff --git a/src/release-notes/lib/release-notes-utils.ts b/src/release-notes/lib/release-notes-utils.ts
index 727a59e91cae..8dd3a9a0afcf 100644
--- a/src/release-notes/lib/release-notes-utils.ts
+++ b/src/release-notes/lib/release-notes-utils.ts
@@ -3,13 +3,8 @@ import { supported, latestStable, latest } from '@/versions/lib/enterprise-serve
import { renderContent } from '@/content-render/index'
import type { Context, GHESReleasePatch, ReleaseNotes } from '@/types'
-/**
- * Create an array of release note objects and sort them by number.
- * Turn { [key]: { notes, intro, date, sections... } }
- * Into [{ version, patches: [ {notes, intro, date, sections... }] }]
- */
export function formatReleases(releaseNotes: ReleaseNotes) {
- // Dot notation, highest first.
+ // Sort dot-formatted release numbers from highest to lowest.
const sortedReleaseNumbers = Object.keys(releaseNotes)
.map((r) => r.replace(/-/g, '.'))
.sort((a, b) => supported.indexOf(a) - supported.indexOf(b))
@@ -19,7 +14,7 @@ export function formatReleases(releaseNotes: ReleaseNotes) {
const patches = Object.keys(notesPerVersion)
.filter((patchNumber) => !notesPerVersion[patchNumber].deprecated)
.map((patchNumber) => {
- // Change version-rc1 to version-rc.1 to make these proper semver RC versions.
+ // Normalize rc1 to rc.1 for release-note version strings.
const patchNumberSemver = patchNumber.replace(/rc/, 'rc.')
return {
...notesPerVersion[patchNumber],
@@ -34,20 +29,12 @@ export function formatReleases(releaseNotes: ReleaseNotes) {
return {
version: releaseNumber,
patches,
- // Lets callers drop release candidates,
- // like the "Supported releases" list on the product landing page.
- // An RC only exists while `latestStable` isn't `latest`.
+ // Lets consumers drop release candidates from supported-release lists.
isReleaseCandidate: latest !== latestStable && releaseNumber === latest,
}
})
}
-/**
- * Render each note in the given patch, by looping through the
- * sections and rendering either `note` or `note.notes` in the
- * case of a sub-section.
- * Returns [{version, patchVersion, intro, date, sections: { features: [], bugs: []...}}]
- */
export async function renderPatchNotes(
patches: GHESReleasePatch[],
ctx: Context,
@@ -58,15 +45,11 @@ export async function renderPatchNotes(
const renderedPatch: GHESReleasePatch = { ...patch, sections: {} }
renderedPatch.intro = await renderContent(patch.intro, ctx)
- // sections looks like { features: [], bugs: [], ... }
const renderedSections = Object.fromEntries(
await Promise.all(
Object.entries(patch.sections).map(async ([sectionType, sectionArray]) => {
- // sectionType is things like 'features', 'bugs', etc.
- // sectionArray is things like [ { heading, notes: [] } ]
const renderedSectionArray = await Promise.all(
sectionArray.map(async (note) => {
- // `note` is either a string or { heading, notes: [] }
if (typeof note === 'string') {
return renderContent(note, ctx)
} else if (typeof note === 'object' && 'heading' in note && 'notes' in note) {
diff --git a/src/release-notes/middleware/get-release-notes.ts b/src/release-notes/middleware/get-release-notes.ts
index 897bb218f653..c4887cf91b74 100644
--- a/src/release-notes/middleware/get-release-notes.ts
+++ b/src/release-notes/middleware/get-release-notes.ts
@@ -1,39 +1,26 @@
import { getDataByLanguage, getDeepDataByLanguage } from '@/data-directory/lib/get-data'
import type { GHESReleasePatch, ReleaseNotes } from '@/types'
-// Widen the union if we ever support release notes for another product.
type ReleaseNotesPrefix = 'enterprise-server'
export function getReleaseNotes(prefix: ReleaseNotesPrefix, langCode: string) {
- // Use English as the foundation, then we'll try to load each individual
- // data/release-notes/**/*.yml file from the translation.
- // If the language is 'en', don't even bother merging.
+ // English release notes define the file set because translation directories can retain stale files.
const releaseNotes = getDeepDataByLanguage(`release-notes.${prefix}`, 'en') as ReleaseNotes
if (langCode === 'en') {
return releaseNotes
}
- // The reason we're doing this is because we can't trust
- // getDeepDataByLanguage() in the translations because it depends on
- // loading in all possible files in the directory. Translations often
- // don't delete files, so we use the English data as a guide for which
- // data files to bother reading.
-
- // `getDeepDataByLanguage()` returns a mutable object from a memoize cache,
- // so build a new one rather than mutating it.
+ // getDeepDataByLanguage returns a mutable object from a memoize cache.
const translatedReleaseNotes: ReleaseNotes = {}
for (const [majorVersion, releases] of Object.entries(releaseNotes)) {
- // Major version is things like '3-7'
translatedReleaseNotes[majorVersion] = {}
for (const minorVersion of Object.keys(releases)) {
- // Minor version is things like '0-rc1' or '3'
const data = getDataByLanguage(
`release-notes.${prefix}.${majorVersion}.${minorVersion}`,
langCode,
) as GHESReleasePatch
- // If any section was mistranslated into something other than an array,
- // fall back to English.
+ // Fall back to English when a translated section is not an array.
const validSections = Object.values(data.sections).every((sectionValue) =>
Array.isArray(sectionValue),
)
diff --git a/src/release-notes/middleware/ghes-release-notes.ts b/src/release-notes/middleware/ghes-release-notes.ts
index 7b2abe3461ba..6ce4b006be76 100644
--- a/src/release-notes/middleware/ghes-release-notes.ts
+++ b/src/release-notes/middleware/ghes-release-notes.ts
@@ -17,25 +17,17 @@ export default async function ghesReleaseNotesContext(
const [requestedPlan, requestedRelease] = req.context.currentVersion.split('@')
if (requestedPlan !== 'enterprise-server') return next()
- // Forced to English.
- // The Markdown in data/release-notes/**/*.yml spells out product names
- // instead of using Liquid variables,
- // so translators render "Le GitHubbe Cöpilotte" instead of "GitHub Copilot".
- // Revisit once those sources use `{% data variables.product.* %}`.
+ // Force English because some release-note entries still spell out product names.
const ghesReleaseNotes = getReleaseNotes('enterprise-server', 'en')
- // If the requested GHES release isn't found in data/release-notes/enterprise-server/*,
- // and it IS a valid GHES release, try being helpful and redirecting to the old location.
- // Otherwise, 404.
+ // Valid releases missing local notes redirect to enterprise.github.com; others return 404.
if (!Object.keys(ghesReleaseNotes).includes(requestedRelease.replace(/\./, '-'))) {
return all.includes(requestedRelease)
? res.safeRedirect(`https://enterprise.github.com/releases/${requestedRelease}.0/notes`)
: next()
}
- // For example, the URL is something like /enterprise-server@3.7/xxx/admin
- // or /enterprise-server@3.7/xxxx/release-notes
- // Then it should not bother because it'll be a 404 anyway.
+ // Paths under the right version but wrong page still return 404 through the normal middleware.
if (!req.context.page) return next()
req.context.ghesReleases = formatReleases(ghesReleaseNotes)
@@ -44,22 +36,17 @@ export default async function ghesReleaseNotesContext(
if (!matchedReleaseNotes) throw new Error('Release notes not found')
const currentReleaseNotes = matchedReleaseNotes.patches
- // The release notes themselves are already forced to English.
- // This forces the reusables to match,
- // while AUTOTITLE links stay in the reader's language.
+ // Render reusables in English while AUTOTITLE links stay in the reader's language.
const originalLanguage = req.context.currentLanguage
req.context.autotitleLanguage = originalLanguage
req.context.currentLanguage = 'en'
try {
- // Render the release notes Markdown.
req.context.ghesReleaseNotes = await executeWithFallback(
req.context,
() => renderPatchNotes(currentReleaseNotes, req.context!),
(enContext: Context) => {
- // Something in the release notes ultimately caused a Liquid
- // rendering error. Let's start over and gather the English release
- // notes instead.
+ // Unreachable while currentLanguage is forced to en; rebuild props if that changes.
enContext.ghesReleases = formatReleases(ghesReleaseNotes)
const enMatchedNotes = enContext.ghesReleases!.find((r) => r.version === requestedRelease)
@@ -72,12 +59,11 @@ export default async function ghesReleaseNotesContext(
req.context.currentLanguage = originalLanguage
}
- // GHES release notes on docs started with 2.20 but older release notes exist on enterprise.github.com.
- // So we want to use _all_ GHES versions when calculating next and previous releases.
+ // latestPatch comes from local notes; latestRelease comes from supported release metadata.
req.context.latestPatch = req.context.ghesReleaseNotes![0].version
req.context.latestRelease = latestStable
- // Add convenience props for "Supported releases" section on GHES Admin landing page (NOT release notes).
+ // Previous-release links include older GHES releases hosted on enterprise.github.com.
for (const release of req.context.ghesReleases) {
release.firstPreviousRelease = all[all.findIndex((v) => v === release.version) + 1]
release.secondPreviousRelease =
diff --git a/src/release-notes/pages/release-notes.tsx b/src/release-notes/pages/release-notes.tsx
index 8408f65222a2..6b4718ab6a16 100644
--- a/src/release-notes/pages/release-notes.tsx
+++ b/src/release-notes/pages/release-notes.tsx
@@ -21,9 +21,7 @@ type Props = {
}
export default function ReleaseNotes({ mainContext, ghesContext }: Props) {
if (!ghesContext) {
- // (Jan 2024) If we some day have more types of release notes, we'll
- // need to make this more forgiving.
- // This component used to cater for GHAE too when that existed.
+ // GHES is the only supported release-notes product.
throw new Error('GHES is the only option')
}
return (
@@ -41,8 +39,7 @@ export const getServerSideProps: GetServerSideProps<Props> = async (
const req = context.req as unknown as ExtendedRequest
const res = context.res as unknown as Response
- // `allVersions[X]` carries more than the components need,
- // so pick only the keys they use.
+ // allVersions entries carry more than these components need, so pick only the keys they use.
const currentVersion = pick(req.context!.allVersions?.[req.context!.currentVersion!] || {}, [
'plan',
'planTitle',
diff --git a/src/release-notes/tests/release-notes.ts b/src/release-notes/tests/release-notes.ts
index 1805dd1539d8..1af118febe9a 100644
--- a/src/release-notes/tests/release-notes.ts
+++ b/src/release-notes/tests/release-notes.ts
@@ -5,8 +5,7 @@ import enterpriseServerReleases from '@/versions/lib/enterprise-server-releases'
import { get, getDOM } from '@/tests/helpers/e2etest'
import Page from '@/frame/lib/page'
-// The English content page's `versions:` frontmatter is the source
-// of (convenient) truth about which versions of this page is available.
+// The English page versions frontmatter defines the versions this page supports.
const page = await Page.init({
basePath: 'content',
relativePath: 'admin/release-notes.md',
@@ -21,7 +20,7 @@ describe('server', () => {
const res = await get('/admin/release-notes')
expect(res.statusCode).toBe(302)
expect(res.headers.location).toBe(
- // Note that English is the default fallback for redirects
+ // English remains the default fallback for redirects.
`/en/enterprise-server@${enterpriseServerReleases.latest}/admin/release-notes`,
)
})
diff --git a/src/secret-scanning/components/SecretScanningTable.tsx b/src/secret-scanning/components/SecretScanningTable.tsx
index 6173e89f4445..b1d0fbf0295d 100644
--- a/src/secret-scanning/components/SecretScanningTable.tsx
+++ b/src/secret-scanning/components/SecretScanningTable.tsx
@@ -14,9 +14,8 @@ const PAGE_SIZE = 25
// Identifies this table in the docs.v0.TableInteractionEvent analytics.
const TABLE_INTERACTION_NAME = 'secret-scanning-patterns'
-// Maps DataTable column ids to the canonical analytics field name so that a
-// filter and a sort on the same column report the same
-// table_interaction_field_name. Filter keys already use these canonical names.
+// Canonical analytics field names keep filter and sort events for the same column
+// grouped together. Filter keys already use these names.
const COLUMN_FIELD_NAMES: Record<string, string> = {
provider: 'provider',
supportedSecret: 'secret',
@@ -59,7 +58,7 @@ export function SecretScanningTable({ data }: { data: SecretScanningData[] }) {
const [sortColumn, setSortColumn] = useState<string | undefined>(undefined)
const [sortDirection, setSortDirection] = useState<'ASC' | 'DESC'>('ASC')
- // Emit a TableInteractionEvent for analytics (github/docs-engineering#6593).
+ // TableInteractionEvent feeds search, filter, sort, and pagination analytics.
const trackInteraction = useCallback(
(interactionType: TableInteractionType, fieldName?: string, fieldValue?: string) => {
sendEvent({
@@ -77,8 +76,7 @@ export function SecretScanningTable({ data }: { data: SecretScanningData[] }) {
const debouncedTrackSearchRef = useRef<ReturnType<typeof debounce> | null>(null)
useEffect(() => {
debouncedTrackSearchRef.current = debounce((query: string) => {
- // Sanitize before logging: users may paste a real secret into this
- // table's search to check support, and the query is sent to analytics.
+ // Sanitize before analytics because users can paste real secrets into this support search.
trackInteraction('search', 'search', sanitizeSearchQuery(query))
}, 500)
return () => {
@@ -263,8 +261,7 @@ export function SecretScanningTable({ data }: { data: SecretScanningData[] }) {
field: 'supportedSecret',
width: '280px',
renderCell: (row) => {
- // The middleware appends HTML for duplicates; strip it.
- // Also handle </br> and <br/> separators in the raw secretType.
+ // Remove duplicate token-versions link; convert raw <br> separators to commas.
const cleanSecretType = row.secretType
.replace(/ <br\/><a href="#token-versions">Token versions<\/a>/, '')
.replace(/<\/?br\s*\/?>/gi, ', ')
diff --git a/src/secret-scanning/pages/api/patterns.ts b/src/secret-scanning/pages/api/patterns.ts
index d8fb0c71369c..38615b48f155 100644
--- a/src/secret-scanning/pages/api/patterns.ts
+++ b/src/secret-scanning/pages/api/patterns.ts
@@ -2,7 +2,7 @@ import type { NextApiRequest, NextApiResponse } from 'next'
import { getSecretScanningData } from '@/secret-scanning/lib/get-secret-scanning-data'
import path from 'path'
-// Returns the cached pattern data as JSON. No HTML rendering here.
+// The API serves cached pattern data as JSON without HTML rendering.
export default async function handler(req: NextApiRequest, res: NextApiResponse) {
const version = (req.query.version as string) || 'fpt'
const filepath = path.join(
@@ -14,7 +14,7 @@ export default async function handler(req: NextApiRequest, res: NextApiResponse)
try {
const data = await getSecretScanningData(filepath)
- // The data only changes on deploy, so cache hard.
+ // The data changes only on deploy, so cache hard.
res.setHeader('Cache-Control', 'public, max-age=3600, s-maxage=86400')
res.json(data)
} catch {
diff --git a/src/secret-scanning/pages/supported-secret-scanning-patterns.tsx b/src/secret-scanning/pages/supported-secret-scanning-patterns.tsx
index 7307840715cc..594e413ab6d5 100644
--- a/src/secret-scanning/pages/supported-secret-scanning-patterns.tsx
+++ b/src/secret-scanning/pages/supported-secret-scanning-patterns.tsx
@@ -43,7 +43,7 @@ export const getServerSideProps: GetServerSideProps<Props> = async (context) =>
addUINamespaces(req, mainContext.data.ui, ['secret_scanning'])
const automatedPageContext = getAutomatedPageContextFromRequest(req)
- // The middleware already loads secretScanningData into req.context
+ // secretScanning middleware loads secretScanningData into req.context.
const patterns = req.context?.secretScanningData ?? []
return {
props: {
diff --git a/src/secret-scanning/scripts/sync.ts b/src/secret-scanning/scripts/sync.ts
index 547767aaa2c6..3f1976d014d4 100755
--- a/src/secret-scanning/scripts/sync.ts
+++ b/src/secret-scanning/scripts/sync.ts
@@ -1,12 +1,6 @@
-/**
- * Required env variables:
- *
- * GITHUB_TOKEN
- *
- * Syncs the
- * https://github.com/github/token-scanning-service/blob/main/docs/public-docs
- * directory to src/secret-scanning/data/pattern-docs
- */
+// Required env variable: GITHUB_TOKEN.
+// Syncs https://github.com/github/token-scanning-service/blob/main/docs/public-docs into
+// src/secret-scanning/data/pattern-docs.
import { writeFile, mkdir } from 'fs/promises'
import { load, dump } from 'js-yaml'
import path from 'path'
diff --git a/src/secret-scanning/tests/liquid-evaluation.ts b/src/secret-scanning/tests/liquid-evaluation.ts
index 63669f985fd3..55a98e8d1fe0 100644
--- a/src/secret-scanning/tests/liquid-evaluation.ts
+++ b/src/secret-scanning/tests/liquid-evaluation.ts
@@ -15,8 +15,8 @@ const { targetFilename } = JSON.parse(
readFileSync('src/secret-scanning/lib/config.json', 'utf8'),
) as { targetFilename: string }
-// Both hasValidityCheck and hasExtendedMetadata can be emitted by token-scanning-service
-// as a Liquid conditional that resolves to false on GHES and true elsewhere.
+// token-scanning-service can emit hasValidityCheck and hasExtendedMetadata as Liquid
+// conditionals that resolve false on GHES and true elsewhere.
const ghesConditional = '{% ifversion ghes %}false{% else %}true{% endif %}'
const makeEntry = (): SecretScanningData =>
diff --git a/src/secret-scanning/tests/rendering.ts b/src/secret-scanning/tests/rendering.ts
index e169df44e0d8..2332b67337ce 100644
--- a/src/secret-scanning/tests/rendering.ts
+++ b/src/secret-scanning/tests/rendering.ts
@@ -20,7 +20,7 @@ describe('secret-scanning pipeline', () => {
const url =
'/en/enterprise-server@3.11/enterprise-cloud@latest/code-security/secret-scanning/introduction/supported-secret-scanning-patterns'
const res = await get(url)
- // It should probably be a 404 because the URL is invalid, but definitely not a 500
+ // Invalid double-version URLs can return 404, but they must not return 500.
expect(res.statusCode).not.toBe(500)
})
})
diff --git a/src/shielding/middleware/handle-invalid-headers.ts b/src/shielding/middleware/handle-invalid-headers.ts
index 857434e2516c..f498dcb6d277 100644
--- a/src/shielding/middleware/handle-invalid-headers.ts
+++ b/src/shielding/middleware/handle-invalid-headers.ts
@@ -3,11 +3,8 @@ import type { Response, NextFunction } from 'express'
import { ExtendedRequest } from '@/types'
const INVALID_HEADER_KEYS = [
- // Next.js will pick this up and override the status code.
- // We don't want that to happen because `x-invoke-status: 203` can
- // trigger the CDN to cache it.
- // It can also trigger a 500 error because the header is not used
- // correctly.
+ // Next.js treats x-invoke-status as the response status, which can make the CDN cache 203s
+ // or turn malformed requests into 500s.
'x-invoke-status',
]
@@ -18,10 +15,7 @@ export default function handleInvalidNextPaths(
) {
const header = INVALID_HEADER_KEYS.find((key) => req.headers[key])
if (header) {
- // There's no point attempting to set a cache-control on this.
- // The CDN will not cache if the status code is not a success
- // and not a 404.
-
+ // The CDN does not cache non-success, non-404 responses.
res.status(400).type('text').send('Invalid request headers')
return
}
diff --git a/src/shielding/middleware/handle-invalid-nextjs-paths.ts b/src/shielding/middleware/handle-invalid-nextjs-paths.ts
index f2ef1f5c8de2..8141544b5d7b 100644
--- a/src/shielding/middleware/handle-invalid-nextjs-paths.ts
+++ b/src/shielding/middleware/handle-invalid-nextjs-paths.ts
@@ -6,16 +6,13 @@ import { ExtendedRequest } from '@/types'
const STATSD_KEY = 'middleware.handle_invalid_nextjs_paths'
+// Development needs /_next/static/webpack and /_next/webpack-hmr.
+// Production blocks /_next/ paths unless they start with /_next/data, plus __nextFallback requests.
export default function handleInvalidNextPaths(
req: ExtendedRequest,
res: Response,
next: NextFunction,
) {
- // For example, `/_next/bin/junk.css`.
- // The reason for depending on checking NODE_ENV is that in development,
- // the Nextjs server will send things like /_next/static/webpack/...
- // or /_next/webpack-hmr.
- // In local dev, we don't get these penetration-testing looking requests.
if (
process.env.NODE_ENV !== 'development' &&
((req.path.startsWith('/_next/') && !req.path.startsWith('/_next/data')) ||
diff --git a/src/shielding/middleware/handle-invalid-paths.ts b/src/shielding/middleware/handle-invalid-paths.ts
index 7b259d55c941..6988c6f4adba 100644
--- a/src/shielding/middleware/handle-invalid-paths.ts
+++ b/src/shielding/middleware/handle-invalid-paths.ts
@@ -3,10 +3,7 @@ import type { Response, NextFunction } from 'express'
import { defaultCacheControl } from '@/frame/middleware/cache-control'
import { ExtendedRequest } from '@/types'
-// We'll check if the current request path is one of these, or ends with
-// one of these.
-// These are clearly intentional "guesses" made by some sort of
-// pen-testing bot.
+// These path guesses come from penetration-testing bots.
const JUNK_STARTS = ['///', '/\\', '/\\.']
const JUNK_ENDS = [
'/package.json',
@@ -28,10 +25,9 @@ const JUNK_PATHS = new Set([
'/_next',
])
-// Basename is the last token of the path when split by `/`.
-// For example `/foo/bar/baz` has a basename of `baz`.
+// Basenames catch nested probes such as /en/code-security/.env.
const JUNK_BASENAMES = new Set([
- // E.g. /en/code-security/.env
+ // Keep .env separate from .env.local matching below.
'.env',
])
@@ -51,18 +47,16 @@ function isJunkPath(path: string) {
}
const basename = path.split('/').pop()
- // E.g. `/billing/.env.local` or `/billing/.env_sample`
+ // Matches /billing/.env.local and /billing/.env_sample.
if (basename && /^\.env(.|_)[\w.]+/.test(basename)) return true
if (basename && JUNK_BASENAMES.has(basename)) return true
- // Prevent various malicious injection attacks targeting Next.js
+ // Block malformed Next.js paths before Next.js handles them.
if (path.match(/^\/_next[^/]/) || path === '/_next/data' || path === '/_next/data/') {
return true
}
- // We currently don't use next/image for any images.
- // This could change in the future but right now can just 404 on these
- // so we don't have to deal with any other errors.
+ // Docs does not use next/image, so these paths can 404 before Next.js handles them.
if (path.startsWith('/_next/image')) {
return true
}
@@ -76,8 +70,7 @@ export default function handleInvalidPaths(
next: NextFunction,
) {
if (isJunkPath(req.path)) {
- // We can let the CDN cache these responses because they are not going
- // to suddenly work in the next deployment.
+ // The CDN can cache scanner responses because the paths will not work in the next deployment.
defaultCacheControl(res)
res.status(404).type('text').send('Not found')
return
diff --git a/src/shielding/middleware/handle-invalid-query-string-values.ts b/src/shielding/middleware/handle-invalid-query-string-values.ts
index 324bbaaa5433..5e738bebb608 100644
--- a/src/shielding/middleware/handle-invalid-query-string-values.ts
+++ b/src/shielding/middleware/handle-invalid-query-string-values.ts
@@ -11,28 +11,13 @@ const logger = createLogger(import.meta.url)
const STATSD_KEY = 'middleware.handle_invalid_querystring_values'
-// Hi future reader!
-// If there are query strings whose values are static and predictable,
-// type them in here.
-// It can't be something like `?query=...` because its value is highly
-// dynamic.
-// At the time of writing, these will match independent of location. A
-// possible extension, in the future, is to make the value match
-// dependent on the location. For example, you might want to express
-// that the values of `?platform=...` should be none when the path is
-// something like `/en/search`.
+// Recognized values must be static across pages; dynamic values such as query stay out.
+// Add path-aware matching if a key needs different values on pages such as /en/search.
const RECOGNIZED_VALUES = {
platform: allPlatforms as string[],
tool: Object.keys(allTools),
}
-// So we can look up if a key in the object is actually present
-// and not a built in.
-// Otherwise...
-//
-// > const myObj = {foo: 'bar'}
-// > 'constructor' in myObj
-// true
-//
+// Use a Set so built-in object properties such as constructor do not count as recognized keys.
const RECOGNIZED_VALUES_KEYS = new Set(Object.keys(RECOGNIZED_VALUES))
export default function handleInvalidQuerystringValues(
@@ -55,8 +40,7 @@ export default function handleInvalidQuerystringValues(
validValues,
})
}
- // Some value is not recognized. Redirect to the current URL
- // but with that query string key removed.
+ // Redirect after removing the query key that contains an unrecognized value.
const sp = new URLSearchParams(query as Record<string, string>)
sp.delete(key)
@@ -72,7 +56,7 @@ export default function handleInvalidQuerystringValues(
}
}
- // For example ?foo[bar]=baz (but not ?foo=bar&foo=baz)
+ // Reject ?foo[bar]=baz, but not ?foo=bar&foo=baz.
if (value instanceof Object && !Array.isArray(value)) {
const message = 'Invalid query string'
defaultCacheControl(res)
diff --git a/src/shielding/middleware/handle-invalid-query-strings.ts b/src/shielding/middleware/handle-invalid-query-strings.ts
index df7c81577c12..df7e85fe95b4 100644
--- a/src/shielding/middleware/handle-invalid-query-strings.ts
+++ b/src/shielding/middleware/handle-invalid-query-strings.ts
@@ -23,36 +23,36 @@ const RECOGNIZED_KEYS_BY_PREFIX = {
}
const RECOGNIZED_KEYS_BY_ANY = new Set([
- // Learning track pages
+ // Learning track pages add these keys.
'learn',
'learnProduct',
- // Platform picker
+ // The platform picker adds this key.
'platform',
- // Tool picker
+ // The tool picker adds this key.
'tool',
- // When apiVersion isn't the only one. E.g. ?apiVersion=XXX&tool=vscode
+ // API pages can combine apiVersion with picker keys such as tool.
'apiVersion',
- // Search results page
+ // Search results pages read this key.
'query',
- // Any page, Search Overlay
+ // The search overlay can add these keys on any page.
'search-overlay-input',
'search-overlay-open',
'search-overlay-ask-ai',
- // The drop-downs on "Webhook events and payloads"
+ // Webhook events pages use actionType for drop-down filtering.
'actionType',
- // Landing page article grid filters
+ // Landing page article grids use these filter keys.
'articles-category',
'articles-filter',
'articles-page',
- // Legacy domain tracking parameter (no longer processed but still recognized)
+ // Recognize the legacy ghdomain parameter even though Docs no longer processes it.
'ghdomain',
- // UTM campaign tracking
+ // UTM campaign links add these keys.
'utm_source',
'utm_medium',
'utm_campaign',
- // Used by experiments
+ // Experiments add this key.
'feature',
- // Used to track API requests from external sources
+ // External API request links add this key.
'client_name',
])
@@ -87,8 +87,7 @@ export default function handleInvalidQuerystrings(
let keys = originalKeys.filter((key) => !RECOGNIZED_KEYS_BY_ANY.has(key))
if (keys.length > 0) {
- // Before we judge the number of query strings, strip out all the ones
- // we're familiar with.
+ // Count only keys this middleware does not recognize for the current path.
for (const [prefix, recognizedKeys] of Object.entries(RECOGNIZED_KEYS_BY_PREFIX)) {
if (path.startsWith(prefix)) {
keys = keys.filter((key) => !recognizedKeys.includes(key))
@@ -96,9 +95,7 @@ export default function handleInvalidQuerystrings(
}
}
- // If you fill out the Survey form with all the fields and somehow
- // don't attempt to make a POST request, you'll end up with a query
- // string like this.
+ // GET and HEAD with hidden survey-token plus real survey-vote match this honeypot branch.
const honeypotted = 'survey-token' in query && 'survey-vote' in query
if (keys.length >= MAX_UNFAMILIAR_KEYS_BAD_REQUEST || honeypotted) {
@@ -118,21 +115,12 @@ export default function handleInvalidQuerystrings(
return
}
- // This is a pattern we've observed in production and we're shielding
- // against it happening again. The root home page is hit with a
- // 8 character long query string that has no value.
+ // Production has sent the home page 8-character valueless query strings.
const rootHomePage = path.split('/').length === 2
const badKeylessQuery =
rootHomePage && keys.length === 1 && keys[0].length === 8 && !query[keys[0]]
- // It's still a mystery why these requests happen but we've seen large
- // number of requests that have a very long URL-encoded query string
- // that starts with 'tool' but doesn't have any value.
- // For example
- // ?tool%25252525253Dvisualstudio%252525253D%2525252526tool%25252525...
- // ...3Dvscode%2525253D%25252526tool%2525253Dvscode%25253D%252526tool...
- // ...%25253Dvimneovim%253D%2526tool%253Djetbrains%3D%26tool%3Djetbrains=&
- // Let's shield against those by removing them.
+ // Strip production keys like tool%25252525253Dvisualstudio...%26tool%3Djetbrains=.
const badToolsQuery = keys.some((key) => key.startsWith('tool%') && !query[key])
if (keys.length >= MAX_UNFAMILIAR_KEYS_REDIRECT || badKeylessQuery || badToolsQuery) {
diff --git a/src/shielding/middleware/handle-malformed-urls.ts b/src/shielding/middleware/handle-malformed-urls.ts
index a5e364b9543b..cb4ec93d66fe 100644
--- a/src/shielding/middleware/handle-malformed-urls.ts
+++ b/src/shielding/middleware/handle-malformed-urls.ts
@@ -3,11 +3,8 @@ import type { Response, NextFunction } from 'express'
import { defaultCacheControl } from '@/frame/middleware/cache-control'
import { ExtendedRequest } from '@/types'
-/**
- * Malformed UTF-8 in a URL, like `%FF`, makes decodeURIComponent throw.
- * Express does not catch that while parsing, so without this the crash
- * happens later at the router level.
- */
+// Malformed UTF-8 in a URL, such as %FF, makes decodeURIComponent throw.
+// Express does not catch that while parsing, so catch it before the router runs.
export default function handleMalformedUrls(
req: ExtendedRequest,
res: Response,
diff --git a/src/shielding/middleware/handle-old-next-data-paths.ts b/src/shielding/middleware/handle-old-next-data-paths.ts
index ac47f1883cbe..9d276ebac1e9 100644
--- a/src/shielding/middleware/handle-old-next-data-paths.ts
+++ b/src/shielding/middleware/handle-old-next-data-paths.ts
@@ -1,24 +1,9 @@
-/**
- * This middleware looks at the URL if it's something like:
- *
- * /_next/data/oOIffMZgfjR6sR9pa50O9/en/free-pro-team%40latest/pages.json?...
- *
- * And from that, it compares that oOIffMZgfjR6sR9pa50O9 with the content
- * of the .next/BUILD_ID file. If they don't match, then it's going to 404.
- * But instead of letting the nextApp.render404() handle it, we're going to
- * manually handle it here.
- * This makes sure the response is a short and fast plain text 404 response.
- * And we can force it to be served with a cache-control which allows
- * the CDN to cache it a bit.
- *
- * Note that when you start the local server with `npm run dev` and
- * do client-side navigation in the app, NextJS will send XHR requests for...
- *
- * /_next/data/development/en/free-pro-team%40latest/pages.json?...
- *
- * Relying on that test is easier than to try to parse the
- * value of `process.env.NODE_ENV`.
- */
+// Next.js data routes include a build ID, for example:
+// /_next/data/oOIffMZgfjR6sR9pa50O9/en/free-pro-team%40latest/pages.json
+// When the build ID does not match .next/BUILD_ID, return a short cacheable 404
+// here instead of letting nextApp.render404 handle it.
+// Local npm run dev uses /_next/data/development/..., so that path stays unblocked
+// without depending on NODE_ENV parsing.
import fs from 'fs'
diff --git a/src/shielding/tests/invalid-querystring-values.ts b/src/shielding/tests/invalid-querystring-values.ts
index 985c6993f546..4b5e7d5f38b9 100644
--- a/src/shielding/tests/invalid-querystring-values.ts
+++ b/src/shielding/tests/invalid-querystring-values.ts
@@ -8,14 +8,11 @@ describe('invalid query string values', () => {
if (key === 'platform') value = 'mac'
else if (key === 'tool') value = 'curl'
else throw new Error('unknown key')
-
- // Valid value
{
const url = `/en/pages?${key}=${value}`
const res = await get(url)
expect(res.statusCode).toBe(200)
}
- // Invalid value
{
const url = `/en/pages?${key}=JUNK&other=thing`
const res = await get(url)
diff --git a/src/shielding/tests/invalid-querystrings.ts b/src/shielding/tests/invalid-querystrings.ts
index 23871850c62e..b00a97578b33 100644
--- a/src/shielding/tests/invalid-querystrings.ts
+++ b/src/shielding/tests/invalid-querystrings.ts
@@ -12,8 +12,7 @@ const alphabet = alpha.map((x) => String.fromCharCode(x))
describe('invalid query strings', () => {
test('400 for too many unrecognized query strings', async () => {
- // This test depends on knowing exactly the number
- // of unrecognized query strings that will trigger a 400.
+ // The exported threshold keeps this test tied to the middleware limit.
const sp = new URLSearchParams()
for (const letter of alphabet.slice(0, MAX_UNFAMILIAR_KEYS_BAD_REQUEST)) {
sp.set(letter, '1')
@@ -27,8 +26,7 @@ describe('invalid query strings', () => {
})
test('302 redirect for many unrecognized query strings', async () => {
- // This test depends on knowing exactly the number
- // of unrecognized query strings that will trigger a redirect.
+ // The exported threshold keeps this test tied to the middleware limit.
const sp = new URLSearchParams()
for (const letter of alphabet.slice(0, MAX_UNFAMILIAR_KEYS_REDIRECT)) {
sp.set(letter, '1')
@@ -58,7 +56,7 @@ describe('invalid query strings', () => {
const res = await get(url)
expect(res.statusCode).toBe(302)
expect(res.headers.location).toBe('/en')
- // But note that it only applies to the home page!
+ // The 8-character rule applies to root-level paths.
{
const nestedUrl = `/en/get-started?${randomCharacters(8)}`
const nestedRes = await get(nestedUrl)
@@ -72,7 +70,7 @@ describe('invalid query strings', () => {
expect(res.statusCode).toBe(400)
expect(res.headers['content-type']).toMatch('text/plain')
expect(res.body).toMatch('Invalid query string')
- // Must not reflect the user-supplied key name
+ // Do not reflect the user-supplied key name.
expect(res.body).not.toContain('(query)')
})
@@ -82,7 +80,7 @@ describe('invalid query strings', () => {
expect(res.statusCode).toBe(400)
expect(res.headers['content-type']).toMatch('text/plain')
expect(res.body).toMatch('Invalid query string')
- // Must not reflect the user-supplied key name
+ // Do not reflect the user-supplied key name.
expect(res.body).not.toContain('(constructor)')
})
@@ -102,11 +100,9 @@ describe('invalid query strings', () => {
expect(res.body).not.toContain('alert')
})
+ // Bug bounty proof of concept: enough unrecognized query keys force a redirect.
+ // safeRedirect normalizes // to / so Location cannot become protocol-relative.
test('redirect from unrecognized query strings does not produce open redirect', async () => {
- // This is the exact PoC from the bug bounty report.
- // With enough unrecognized query keys, the middleware redirects
- // using req.path. res.safeRedirect normalizes // to / so the
- // Location header can never be a protocol-relative URL.
const res = await get('//evil.com?a=1&b=2&c=3')
expect(res.headers.location).not.toMatch(/^\/\//)
})
diff --git a/src/shielding/tests/malformed-urls.ts b/src/shielding/tests/malformed-urls.ts
index 2777e90d6c9f..6219095fdc0a 100644
--- a/src/shielding/tests/malformed-urls.ts
+++ b/src/shielding/tests/malformed-urls.ts
@@ -34,7 +34,8 @@ describe('malformed URLs', () => {
test('allows URLs with control characters (valid UTF-8)', async () => {
// %01 decodes fine, so the middleware lets it through.
const res = await get('/en/test-%01-page')
- expect(res.statusCode).toBe(404) // 404 because the page does not exist, not 400
+ // The page does not exist, so a valid URL returns 404 instead of 400.
+ expect(res.statusCode).toBe(404)
})
test('allows valid URLs with proper encoding', async () => {
@@ -48,7 +49,7 @@ describe('malformed URLs', () => {
})
test('blocks malformed query parameters', async () => {
- // This is caught by checking originalUrl which contains the raw, unparsed URL
+ // originalUrl keeps the raw, unparsed query string.
const res = await get('/en/search?q=test%FF')
expect(res.statusCode).toBe(400)
expect(res.headers['content-type']).toMatch('text/plain')
diff --git a/src/shielding/tests/shielding.ts b/src/shielding/tests/shielding.ts
index dd81e2ebce0d..43d297158c67 100644
--- a/src/shielding/tests/shielding.ts
+++ b/src/shielding/tests/shielding.ts
@@ -30,8 +30,7 @@ describe('junk paths', () => {
test('double-slash with query params does not open redirect', async () => {
const res = await get('//evil.com?a=1&b=2&c=3')
- // With 3 unrecognized query keys, the query string middleware redirects
- // using res.safeRedirect which normalizes // to /
+ // With 3 unrecognized query keys, safeRedirect normalizes // to /.
expect(res.headers.location).not.toMatch(/^\/\//)
})
@@ -96,7 +95,7 @@ describe('index.md and .md suffixes', () => {
// .md is stripped and request flows through with Accept: text/markdown
{
const res = await get('/en/get-started.md')
- // Should not redirect — serves markdown directly (or 404 if page doesn't exist)
+ // Serves markdown directly or returns 404 when the page does not exist.
expect(res.statusCode).not.toBe(301)
expect(res.statusCode).not.toBe(302)
}
diff --git a/src/tests/helpers/caching-headers.ts b/src/tests/helpers/caching-headers.ts
index a8fc1bcf7fd1..4b9f201d18ff 100644
--- a/src/tests/helpers/caching-headers.ts
+++ b/src/tests/helpers/caching-headers.ts
@@ -22,15 +22,13 @@ export function checkCachingHeaders(
}
const maxAgeSeconds = parseInt(maxAgeMatch[1], 10)
- // Let's not be too specific in the tests, just as long as it's testing
- // that it's a reasonably large number of seconds.
+ // Use a lower bound so tests tolerate normal cache-window changes.
expect(maxAgeSeconds).toBeGreaterThanOrEqual(minMaxAge)
const surrogateKeyHeader = res.headers['surrogate-key'] as string
const firstToken = surrogateKeyHeader.split(/\s/g)[0]
if (defaultSurrogateKey) {
- // Default cacheable responses are keyed by language for the staggered,
- // per-language deploy purge: either `no-language` or `language:<code>`.
+ // Per-language purges need no-language or language:<code> as the first surrogate key.
expect(firstToken === 'no-language' || /^language:[a-z-]+$/.test(firstToken)).toBe(true)
} else {
expect(firstToken).toBe(SURROGATE_ENUMS.MANUAL)
diff --git a/src/tests/helpers/check-url.ts b/src/tests/helpers/check-url.ts
index 6f05e4f960d3..a3a19c86a21c 100644
--- a/src/tests/helpers/check-url.ts
+++ b/src/tests/helpers/check-url.ts
@@ -6,15 +6,9 @@ import type { Context } from '@/types'
const liquidStartRex = /^{%-?\s*ifversion .+?\s*%}/
const liquidEndRex = /{%-?\s*endif\s*-?%}$/
-// Return
-//
-// /foo/bar
-//
-// if the text input was
-//
-// {% ifversion ghes%}/foo/bar{%endif %}
-//
-// And if no liquid, just return as is.
+// Frontmatter link lists sometimes wrap paths in ifversion Liquid; checks need the raw path.
+// Example input: {% ifversion ghes%}/foo/bar{%endif %}
+// Output: /foo/bar
function stripLiquid(text: string): string {
if (liquidStartRex.test(text) && liquidEndRex.test(text)) {
return text.replace(liquidStartRex, '').replace(liquidEndRex, '').trim()
@@ -24,27 +18,20 @@ function stripLiquid(text: string): string {
return text
}
-// Given a URI that does not start with a specific language,
-// return undefined if it can found as a known page.
-// Otherwise, return an object with information that is used to
-// print a useful test error message in the assertion.
+// Return details for assertion errors when a language-free URI cannot resolve to a known page.
export function checkURL(uri: string, index: number, redirectsContext: Context) {
const url = `/en${stripLiquid(uri).split('#')[0]}`
if (!redirectsContext.pages || !(url in redirectsContext.pages)) {
- // Some are written without a version, but don't work with the
- // default version.
+ // Some unversioned links resolve only after redirects add a version.
let redirects = getRedirect(url, redirectsContext)
- // If it does indeed redirect to a different version,
- // strip that and compare again.
if (redirects) {
const withoutVersion = getPathWithoutVersion(redirects)
if (withoutVersion === url) {
- // That means, it's actually fine
return null
}
redirects = getPathWithoutLanguage(withoutVersion)
}
return { uri, index, redirects }
}
- return null // Falsy value will be filtered out later
+ return null
}
diff --git a/src/tests/helpers/data-directory.ts b/src/tests/helpers/data-directory.ts
index a61d332a6271..a39240d69afa 100644
--- a/src/tests/helpers/data-directory.ts
+++ b/src/tests/helpers/data-directory.ts
@@ -8,42 +8,12 @@ interface DataStructure {
[key: string]: string | DataStructure
}
-// This helper class exists so you can create a temporary root directory
-// full of data files.
-// For example, if you want to unit test with files that are not part
-// of the git repo but should only "temporarily" exist for the duration
-// of the tests.
-// This class takes an object and generates that as files on disk. E.g.
-//
-// const dataDirectory = new DataDirectory({
-// data: {
-// reusables: {
-// example: 'a rose by any other name\nwould smell as sweet',
-// },
-// },
-// })
-// process.env.ROOT = dataDirectory.root
-// ...
-// try {
-// ...unit tests here...
-// } finally {
-// dataDirectory.destroy()
-// }
-//
-// Note that it's very specific about keys. For example, if the nested
-// object has a key called 'ui' it doesn't create a deeper nested structure
-// but takes the nested structure and writes it to a single .yml file.
-// For example:
-//
-// const dataDirectory = new DataDirectory({
-// data: {
-// ui: {
-// key: "Value",
-// deep: {
-// er: "Stuff"
-//
-// will create a single <tempdir>/data/ui.yml file.
-//
+// DataDirectory builds a temporary data root for tests that need files outside the repository.
+// It writes nested data objects to disk, then destroy removes the temp root.
+// Example: new DataDirectory({ data: { reusables: { example: 'temporary text' } } }).
+// Point ROOT at dataDirectory.root during the test, then call dataDirectory.destroy().
+// Special keys match production data conventions: ui writes data/ui.yml, variables write .yml
+// files, and reusables write .md files.
export class DataDirectory {
root: string
@@ -71,7 +41,7 @@ export class DataDirectory {
fs.writeFileSync(path.join(here, `${key}.md`), value, 'utf-8')
} else {
fs.mkdirSync(path.join(here, key))
- // Using 'as' assertion because we know value must be an object when it's not a string in reusables context
+ // The reusables branch already ruled out strings.
this.create(value as DataStructure, path.join(here, key), false, true)
}
} else if (isVariables) {
@@ -82,7 +52,7 @@ export class DataDirectory {
} else {
const there = path.join(here, key)
fs.mkdirSync(there)
- // Using 'as' assertions because nested directory values are always objects, not strings
+ // Nested directory branches only handle objects.
if (key === 'reusables') {
this.create(value as DataStructure, there, false, true)
} else if (key === 'variables') {
diff --git a/src/tests/helpers/e2etest.ts b/src/tests/helpers/e2etest.ts
index 7bd87f4b8bd5..8b4a8f7cd825 100644
--- a/src/tests/helpers/e2etest.ts
+++ b/src/tests/helpers/e2etest.ts
@@ -82,7 +82,7 @@ export async function get<T extends ResponseTypes = 'text'>(
headersRecord[key] = value
}
- // Return response in got-compatible format
+ // Tests still expect got-compatible response fields.
return {
body: responseBody,
statusCode: response.status,
@@ -116,7 +116,7 @@ export async function getDOMCached(
const $ = await getDOM(route, options)
getDOMCache.set(key, $)
}
- // The non-null assertion is safe here because we've just set the key if it didn't exist
+ // The cache sets the key before this lookup.
return getDOMCache.get(key)!
}
@@ -134,9 +134,9 @@ export async function getDOM(route: string, options: GetDOMOptions = {}): Promis
const $ = load(res.body || '', { xmlMode: true })
const result = $ as CachedDOMResult
- // Attach res to the cheerio object for backward compatibility
+ // Older tests read the response from the Cheerio object.
result.res = res
- // Attach $ to itself for destructuring compatibility
+ // Older tests destructure $ from the Cheerio object.
result.$ = result
return result
diff --git a/src/tests/helpers/schemas.ts b/src/tests/helpers/schemas.ts
index cb35e6c84319..e1896f82b772 100644
--- a/src/tests/helpers/schemas.ts
+++ b/src/tests/helpers/schemas.ts
@@ -1,35 +1,22 @@
import type { ErrorObject } from 'ajv'
-// lightly format the schema errors object returned from ajv to connect the
-// error message to where the problem is -- for example, if a top level 'date'
-// property isn't correctly formatted as a date we return:
-//
-// at 'date': must match format "date"
-//
-// if sections > features has an array of objects that must have a 'notes'
-// property and we misspell the property name in the first item:
-//
-// at 'sections > features > item 0': must have required property 'notes'
+// Format AJV errors with the path first, so data-file failures point at the bad value.
+// Example: at 'sections > features > item 0': must have required property 'notes'
export const formatAjvErrors = (errors: ErrorObject[] = []): string => {
return errors
.map((errorObj) => {
- // ajv instancePath tells us in the data we're checking where there was a
- // schema error -- for release notes looks like this for example
- // `/sections/features/0` if the error is in the first feature under sections.
+ // instancePath points to the failing data path, such as /sections/features/0.
const split = errorObj.instancePath.split('/')
split.shift()
- // handle additional properties error specifically since we can call out
- // which property shouldn't be there
+ // Call out the unexpected property name for additionalProperties errors.
let additionalProperties = ''
if (errorObj.keyword === 'additionalProperties') {
additionalProperties = `: additional property is '${errorObj.params.additionalProperty}'`
}
- // ajv's enum message is "must be equal to one of the allowed values" but
- // does not name them, which is not actionable when the schema lives in a
- // different file than the data being validated
+ // AJV omits enum values from its message, but schema-file lookups need actionable values.
let allowedValues = ''
if (errorObj.keyword === 'enum' && Array.isArray(errorObj.params.allowedValues)) {
diff --git a/src/tests/helpers/schemas/products-schema.ts b/src/tests/helpers/schemas/products-schema.ts
index 3da38b902727..4b0fb77b1fee 100644
--- a/src/tests/helpers/schemas/products-schema.ts
+++ b/src/tests/helpers/schemas/products-schema.ts
@@ -15,19 +15,19 @@ export default {
href: {
description: 'the href to the product landing page',
type: 'string',
- pattern: '^(/|http)', // if internal, must start with a slash; if external, must start with http
+ pattern: '^(/|http)', // Internal hrefs start with /; external hrefs start with http.
},
dir: {
description: 'the local relative path to the product directory',
type: 'string',
- pattern: '^content/.*?[^/]$', // must start with content, can't end with a slash
+ pattern: '^content/.*?[^/]$', // Product directories start with content and omit a trailing slash.
},
toc: {
description: 'the local relative path to the product toc page',
type: 'string',
- pattern: '^content/.*?index.md$', // must start with content and end with index.md
+ pattern: '^content/.*?index.md$', // TOC files start with content and end with index.md.
},
hasEnterpriseUserVersions: {
diff --git a/src/tests/helpers/schemas/versions-schema.ts b/src/tests/helpers/schemas/versions-schema.ts
index 44b84bf50ce6..e76431d37d86 100644
--- a/src/tests/helpers/schemas/versions-schema.ts
+++ b/src/tests/helpers/schemas/versions-schema.ts
@@ -1,5 +1,4 @@
-// match plan@release
-// e.g., free-pro-team@latest, enterprise-server@3.0
+// Version strings match plan@release, for example free-pro-team@latest or enterprise-server@3.XX.
const planPattern = '^[a-z-]+'
const releasePattern = '[a-z0-9-.]+'
const delimiter = '@'
@@ -63,7 +62,7 @@ const schema: VersionSchema = {
pattern: planPattern,
},
planTitle: {
- description: 'the plan title', // this is the same as the version title, sans numbered release
+ description: 'the plan title', // planTitle matches versionTitle without the numbered release.
type: 'string',
},
shortName: {
@@ -90,7 +89,8 @@ const schema: VersionSchema = {
type: 'boolean',
},
nonEnterpriseDefault: {
- description: 'boolean indicating whether the plan is the default non-Enterprise version', // helper if the plan name changes
+ // Identifies the default non-Enterprise version without hard-coding a plan name.
+ description: 'boolean indicating whether the plan is the default non-Enterprise version',
type: 'boolean',
},
openApiBaseName: {
diff --git a/src/tests/lib/validate-json-schema.ts b/src/tests/lib/validate-json-schema.ts
index b20418628e60..76c8efa913ef 100644
--- a/src/tests/lib/validate-json-schema.ts
+++ b/src/tests/lib/validate-json-schema.ts
@@ -10,12 +10,8 @@ addErrors(ajv)
ajv.addKeyword({
keyword: 'translatable',
})
-// Schemas can contain the custom keyword `lintable` to define
-// a property as a Markdown string that can be linted by the
-// content linter.
-// The custom keyword does not define a custom validator function.
-// This allows the custom keyword to be present in a schema but
-// doesn't perform additional validation other than type checking.
+// The lintable keyword marks Markdown strings that the content linter can check.
+// AJV still validates only the string type.
ajv.addKeyword({
keyword: 'lintable',
type: 'string',
@@ -25,21 +21,13 @@ ajv.addFormat('semver', {
validate: (x: string): boolean => semver.validRange(x) !== null,
})
-// The ajv.validate function is supposed to cache
-// the compiled schema, but the documentation says
-// that the best performance is achieved by calling
-// the compile function and then calling validate.
-// So when the same schema is validated multiple times,
-// this is the best function to use. If the schema
-// changes from one call to the next, then the validateJson
-// function makes more sense to use.
+// Reuse compiled validators when one schema validates multiple payloads.
+// Use validateJson when each call may receive a different schema.
export function getJsonValidator(schema: SchemaObject): ValidateFunction {
return ajv.compile(schema)
}
-// The next call to ajv.validate will overwrite
-// the ajv.errors property, so returning it here
-// ensures that it remains accessible.
+// Clone AJV errors before the next validate call overwrites ajv.errors.
export function validateJson(
schema: SchemaObject,
data: unknown,
diff --git a/src/tests/mocks/cse-copilot-mock.ts b/src/tests/mocks/cse-copilot-mock.ts
index 6e1d0e8b6094..dbfd0d51fb1a 100644
--- a/src/tests/mocks/cse-copilot-mock.ts
+++ b/src/tests/mocks/cse-copilot-mock.ts
@@ -1,6 +1,6 @@
import { Request, Response } from 'express'
-// Prefix used for mocking. This can be any value
+// Tests use this prefix only to mount the mock route; any stable value works.
export const CSE_COPILOT_PREFIX = 'cse-copilot'
export function cseCopilotPostAnswersMock(req: Request, res: Response) {
diff --git a/src/tests/mocks/start-mock-server.ts b/src/tests/mocks/start-mock-server.ts
index 9236b73a60e6..b3a82d05c9e0 100644
--- a/src/tests/mocks/start-mock-server.ts
+++ b/src/tests/mocks/start-mock-server.ts
@@ -1,24 +1,7 @@
-/* When testing API routes via an integration test, e.g.
-
-const res = await post('/api/<some-route>', {
- body: JSON.stringify(api_body),
- headers: { 'Content-Type': 'application/json' },
-})
-
-expect(res.status).toBe(200)
-
-The `api/<route>` may call an external URL.
-
-We are unable to use `nock` in this circumstance since we run the server in a separate instance.
-
-Instead, we can use the `startMockServer` helper to start a mock server that will intercept the request and return a canned response.
-
-In order for this to work you MUST use a process.env variable for the URL you are calling,
-
-e.g. `process.env.CSE_COPILOT_ENDPOINT`
-
-You should override the variable in the overrideEnvForTesting function in this file.
-*/
+// Integration tests cannot use nock when API routes call external URLs from a separate server.
+// Example: post to /api/<some-route>, and let that route call the mock server.
+// Point the route at this mock server through an env var such as CSE_COPILOT_ENDPOINT.
+// Set that env var in overrideEnvForTesting.
import express from 'express'
import type { Server } from 'http'
diff --git a/src/tests/scripts/copy-fixture-data.ts b/src/tests/scripts/copy-fixture-data.ts
index cc2ad6437747..dc8fc04092b3 100755
--- a/src/tests/scripts/copy-fixture-data.ts
+++ b/src/tests/scripts/copy-fixture-data.ts
@@ -1,14 +1,5 @@
-// [start-readme]
-//
-// There are certain files that have to be manually copied from the
-// real data into the test fixture data.
-//
-// This script copies the files from `data/` into `tests/fitures/data/...`
-// that are files that are both needed for fixture testing yet can't
-// live with the code. For example, `data/ui.yml` is part of the rendering
-// code, but it lives in `data/` so it can be translated.
-//
-// [end-readme]
+// Some fixture tests need translated data files that live under data, outside test code.
+// This script copies those required data files into src/fixtures/fixtures/data.
import fs from 'fs'
import path from 'path'
@@ -16,8 +7,7 @@ import path from 'path'
import { program } from 'commander'
import chalk from 'chalk'
-// Here, write down all the files that are actually part of the rendering
-// functionality yet live in data.
+// Keep files that rendering needs but stores under data.
const MANDATORY_FILES = [
'data/ui.yml',
'data/reusables/enterprise_deprecation/deprecation_details.md',
diff --git a/src/tests/scripts/copy-to-test-repo.sh b/src/tests/scripts/copy-to-test-repo.sh
index f82f54f0349f..03f8ce9df386 100755
--- a/src/tests/scripts/copy-to-test-repo.sh
+++ b/src/tests/scripts/copy-to-test-repo.sh
@@ -1,7 +1,7 @@
#!/bin/bash
-# Copies certain directories over to docs-internal-test and pushes. Useful for debugging actions
-# Doesn't copy over content/ and data/ directories
+# Copies selected files to docs-internal-test and pushes them for GitHub Actions debugging.
+# Excludes content, data, node_modules, Git metadata, .gitattributes, and .github/CODEOWNERS.
echo "Make sure to run this script in the root path of docs-internal!"
@@ -39,5 +39,3 @@ fi;
exit
-
-
diff --git a/src/tools/components/Fields.tsx b/src/tools/components/Fields.tsx
index 635446920d10..7e0fcf9d9593 100644
--- a/src/tools/components/Fields.tsx
+++ b/src/tools/components/Fields.tsx
@@ -30,11 +30,7 @@ export const Fields = (fieldProps: {
if (onSelect) onSelect(item)
setOpen(!open)
}}
- // These extra links in the pickers are not a part of the selection variant
- // in that they are generally external links, so we want to remove the selection
- // variant span box in front of it. To date there isn't a possibility to have
- // an ActionMenu in Primer that allow non-selection variant items with selection
- // variant items
+ // Primer ActionMenu cannot mix selection items with external links, so extras hide the indicator.
className={cx(
(item.extra?.arrow || item.extra?.info) && styles.extrasDisplay,
styles.linkItem,
diff --git a/src/tools/components/InArticlePicker.module.scss b/src/tools/components/InArticlePicker.module.scss
index 47edd48cfd44..072817233a7b 100644
--- a/src/tools/components/InArticlePicker.module.scss
+++ b/src/tools/components/InArticlePicker.module.scss
@@ -1,11 +1,9 @@
.container {
- // Override Primer's selected tab indicator color to meet WCAG 1.4.11
- // non-text contrast minimum of 3:1. The default --color-primer-border-active
- // (#FD8C73) has only 2.3:1 contrast. Using a Primer theme variable
- // that meets contrast in both light and dark color modes.
+ // Primer's --color-primer-border-active has 2.3:1 contrast and fails WCAG 1.4.11.
+ // --color-severe-emphasis meets the 3:1 minimum in light and dark modes.
--underlineNav-borderColor-active: var(--color-severe-emphasis);
- // target the ActionList dropdown that appears when UnderlineNav overflows
+ // Primer does not expose a stable class for the UnderlineNav overflow ActionList.
ul[class*="prc-ActionList-ActionList"] {
background-color: var(
--overlay-bgColor,
diff --git a/src/tools/components/InArticlePicker.tsx b/src/tools/components/InArticlePicker.tsx
index f8c9dbe52973..0b726836f1c9 100644
--- a/src/tools/components/InArticlePicker.tsx
+++ b/src/tools/components/InArticlePicker.tsx
@@ -14,9 +14,9 @@ type Option = {
label: string
}
type Props = {
- // Use this if not specified on the query string
+ // Used when the query string does not specify a valid value.
defaultValue?: string
- // Use this if not specified on the query string or no cookie
+ // Used when the query string is invalid, defaultValue is unset, and the cookie is invalid.
fallbackValue: string
cookieKey: string
queryStringKey: string
@@ -39,12 +39,9 @@ export const InArticlePicker = ({
const { query, locale } = router
const [currentValue, setCurrentValue] = useState('')
- // Tracks whether the last currentValue change was triggered by a user click
- // (as opposed to initial mount or external navigation). When true, we move
- // focus to the newly-selected tab so keyboard users don't lose their place.
+ // True after user clicks, so focus moves only for direct tab selection.
const focusAfterNavRef = useRef(false)
- // Run on mount for client-side only features
useEffect(() => {
const raw = query[queryStringKey]
let value = ''
@@ -52,8 +49,7 @@ export const InArticlePicker = ({
if (Array.isArray(raw)) value = raw[0]
else value = raw
}
- // Only pick it up from the possible query string if its value
- // is a valid option.
+ // Ignore query string values outside this picker's options.
const possibleValues = options.map((option) => option.value)
if (!value || !possibleValues.includes(value)) {
const cookieValue = Cookies.get(cookieKey)
@@ -70,49 +66,24 @@ export const InArticlePicker = ({
const [asPathRoot, asPathQuery = ''] = router.asPath.split('#')[0].split('?')
- // Use a layout effect so the DOM mutation (hiding non-matching .ghd-tool
- // content) happens before the browser paints. With React 19's stricter
- // effect timing, a regular useEffect could leave non-matching content
- // visible on initial page load until after first paint.
+ // Apply the selection before paint so non-matching .ghd-tool content does not flash.
useIsomorphicLayoutEffect(() => {
- // This will make the hook run this callback on mount and on change.
- // That's important because even though the user hasn't interacted
- // and made an overriding choice, we still want to run this callback
- // because the page might need to be corrected based on *a* choice
- // independent of whether it's a change.
+ // Initial values still need to update the page before the user interacts.
if (currentValue) {
onValue(currentValue)
}
}, [
currentValue,
- // This is important because we can't otherwise rely on the firing
- // of this effect on initial mount. It also needs to fire when the
- // URL (i.e. route) changes.
- // Don't use `router.asPath` because that contains the query string
- // which we handle in the other useEffect above.
+ // Query string changes are handled separately, so depend on the route path only.
asPathRoot,
])
- // This is exclusively for local development.
- // If you're in local development, you have the <ClientSideRefresh>
- // causing a XHR refresh of the content triggered by the Page Visibility
- // API (implemented in the uswSWR hook). That means that on the pages that
- // contain these `.ghd-tool` classes, any DOM changes we might
- // have previously made are lost and started over.
+ // Local ClientSideRefresh replaces article HTML on visibility changes, so reapply selection.
useEffect(() => {
let mounted = true
const toggleVisibility = () => {
if (document.visibilityState === 'visible') {
- // We don't need to track this timer, and possibly cancel it on
- // dismount, because within the callback we use the `mounted`
- // boolean which means we can know to do nothing if the parent
- // component has been dismounted.
- // The reason this is wrapped in a short timeout is because the
- // React rendering might not actually have fully updated the DOM
- // (from the XHR HTML it receives) so allow the DOM to refresh
- // first before asking it to change. The number can be quite low
- // (which is sufficient for human eyes) but must be at least
- // in the lower hundreds of milliseconds.
+ // Keep at least a 100 ms delay so refreshed HTML reaches the DOM before selection changes it.
setTimeout(() => {
if (mounted) {
onValue(currentValue)
@@ -148,10 +119,7 @@ export const InArticlePicker = ({
Cookies.set(cookieKey, value)
}
- // After a user clicks a tab, the shallow route change updates `currentValue`.
- // Once the DOM reflects the new selection (aria-current="page" is on the new
- // tab), move keyboard focus there so the user's context is preserved.
- // WCAG 2.4.3 Focus Order: focus must land on the triggered control.
+ // WCAG 2.4.3 requires focus to remain on the triggered tab after shallow routing.
useEffect(() => {
if (!focusAfterNavRef.current || !currentValue) return
focusAfterNavRef.current = false
@@ -171,7 +139,7 @@ export const InArticlePicker = ({
return (
<div data-testid={`${queryStringKey}-picker`} className={styles.container}>
- {/* The key attribute is required for a bug in UnderlineNav that doesn't render the component when there are changes to the items. */}
+ {/* UnderlineNav can miss item changes without a changing key. */}
<UnderlineNav key={router.asPath} {...sharedContainerProps}>
{options.map((option) => {
params.set(queryStringKey, option.value)
diff --git a/src/tools/components/PlatformPicker.tsx b/src/tools/components/PlatformPicker.tsx
index 7d78b2e48e6c..e113fdd96003 100644
--- a/src/tools/components/PlatformPicker.tsx
+++ b/src/tools/components/PlatformPicker.tsx
@@ -13,7 +13,7 @@ const platforms = [
{ value: 'linux', label: 'Linux' },
]
-// Note: platform === os
+// Content calls this preference platform, but the stored preference name is os.
export const PlatformPicker = () => {
const { defaultPlatform, detectedPlatforms } = useArticleContext()
@@ -28,9 +28,7 @@ export const PlatformPicker = () => {
setDefaultUA(userAgent)
}, [])
- // Defensively, just in case some article happens to have an array
- // but for some reasons, it might be empty, let's not have a picker
- // at all.
+ // Articles with no detected platforms do not need a picker.
if (!detectedPlatforms.length) return null
const options = platforms.filter((platform) => detectedPlatforms.includes(platform.value))
@@ -46,9 +44,7 @@ export const PlatformPicker = () => {
cookieKey={OS_PREFERRED_COOKIE_NAME}
queryStringKey={platformQueryKey}
onValue={(value: string) => {
- // Visibility is driven by React state via ToggleableContent/MiniTocs
- // (#6619); the article body is React-owned on both the hast and string
- // paths, so no imperative DOM mutation is needed.
+ // React state drives visibility because the article body is React-owned.
setPlatform(value)
}}
preferenceName="os"
diff --git a/src/tools/components/SelectionContext.tsx b/src/tools/components/SelectionContext.tsx
index 0c09457855b6..5032ab8d1477 100644
--- a/src/tools/components/SelectionContext.tsx
+++ b/src/tools/components/SelectionContext.tsx
@@ -4,17 +4,10 @@ import type { ReactNode } from 'react'
import { allPlatforms } from '@/tools/lib/all-platforms'
import { allTools } from '@/tools/lib/all-tools'
-// React-native replacement for the imperative platform/tool visibility toggling
-// that PlatformPicker/ToolPicker used to do by walking the DOM and setting
-// `style.display` on `.ghd-tool`/`.platform-*`/`.tool-*` elements (#6619). The
-// selected platform + tool live in this context; the article body (rendered from
-// hast) maps the relevant elements to <ToggleableContent>, which reads the
-// selection and hides non-matching content instead of mutating React-owned nodes.
-//
-// Selections start empty so that the server render and the first client render
-// both show ALL variants (matching the pre-JS markup), which keeps hydration
-// stable. The pickers set the real selection in an effect after hydration, the
-// same moment the old imperative code used to run.
+// PlatformPicker and ToolPicker store selection here so ToggleableContent can
+// hide React-owned article elements without imperative style.display mutations.
+// Empty initial selections keep server and first client renders showing all variants,
+// which matches pre-JS markup and keeps hydration stable.
export type SelectionContextT = {
platform: string
@@ -62,14 +55,10 @@ function toClassList(className: unknown): string[] {
return []
}
-// Determine whether an element is platform/tool-scoped and which value gates it.
-// `.ghd-tool <value>` is a block (the {% mac %}/{% webui %} liquid tags); the
-// extra class is the platform or tool value. `platform-<value>`/`tool-<value>`
-// are author-written inline spans. We classify strictly against the canonical
-// platform/tool vocabularies and return null on anything outside them, so an
-// unrecognized class never makes content disappear. When several recognized
-// markers are present the first match wins; in practice an element carries
-// exactly one platform/tool marker.
+// .ghd-tool uses a separate class for the platform or tool value.
+// platform-<value> and tool-<value> are author-written inline spans.
+// Strict vocabulary checks prevent unknown classes from hiding content.
+// .ghd-tool prefers a recognized platform; inline spans use the first recognized marker.
export function classifyToggleClass(className: unknown): ToggleClassification | null {
const classes = toClassList(className)
if (!classes.length) return null
@@ -100,8 +89,7 @@ export function isToggleClass(className: unknown): boolean {
return classifyToggleClass(className) !== null
}
-// Visible when no selection has been made yet (initial render shows everything,
-// matching the pre-JS markup) or when the element's value is the selected one.
+// Empty initial selections show everything, matching the pre-JS markup.
export function isContentVisible(
classification: ToggleClassification,
selection: { platform: string; tool: string },
diff --git a/src/tools/components/ToggleableContent.tsx b/src/tools/components/ToggleableContent.tsx
index c1e114897032..0659ace2a6a6 100644
--- a/src/tools/components/ToggleableContent.tsx
+++ b/src/tools/components/ToggleableContent.tsx
@@ -7,12 +7,8 @@ import {
useSelection,
} from '@/tools/components/SelectionContext'
-// Wraps a platform/tool-scoped element from the article body hast and toggles
-// its visibility from SelectionContext instead of the old imperative
-// `style.display` mutation (#6619). Renders the same element/props/children, but
-// sets `hidden` when the current platform/tool selection doesn't match. We keep
-// the node in the DOM (hidden) rather than returning null so anchors, IDs, and
-// screen-reader traversal behave like the previous `display:none` approach.
+// ToggleableContent keeps hidden article nodes in the DOM so anchors, IDs, and
+// screen-reader traversal match the previous display:none behavior.
type ToggleableContentProps = {
tag: 'div' | 'span'
className?: string
diff --git a/src/tools/components/ToolPicker.tsx b/src/tools/components/ToolPicker.tsx
index 94748f6b1523..e0565ff98f0b 100644
--- a/src/tools/components/ToolPicker.tsx
+++ b/src/tools/components/ToolPicker.tsx
@@ -3,18 +3,16 @@ import { InArticlePicker } from './InArticlePicker'
import { useSelection } from './SelectionContext'
import { TOOL_PREFERRED_COOKIE_NAME } from '@/frame/lib/constants'
-// Example page with a tool picker:
-// http://localhost:4000/en/codespaces/developing-in-codespaces/creating-a-codespace
-
-// Note: tool === application, and picker === switcher
+// Example tool picker page: /en/codespaces/developing-in-codespaces/creating-a-codespace
+// Content calls this preference tool, but the stored preference name is application.
function getDefaultTool(defaultTool: string | undefined, detectedTools: Array<string>): string {
if (defaultTool && detectedTools.includes(defaultTool)) return defaultTool
- // Default to webui if present (this is generally the case where we show UI/CLI/Desktop info)
+ // UI, CLI, and Desktop articles default to webui.
if (detectedTools.includes('webui')) return 'webui'
- // Default to cli if present (this is generally the case where we show curl/CLI info)
+ // Curl and CLI articles default to cli.
if (detectedTools.includes('cli')) return 'cli'
return detectedTools[0]
@@ -37,9 +35,7 @@ export const ToolPicker = () => {
cookieKey={TOOL_PREFERRED_COOKIE_NAME}
queryStringKey={toolQueryKey}
onValue={(value: string) => {
- // Visibility is driven by React state via ToggleableContent/MiniTocs
- // (#6619); the article body is React-owned on both the hast and string
- // paths, so no imperative DOM mutation is needed.
+ // React state drives visibility because the article body is React-owned.
setTool(value)
}}
preferenceName="application"
diff --git a/src/tools/lib/all-platforms.ts b/src/tools/lib/all-platforms.ts
index 13845752f6a4..62636fde0b0f 100644
--- a/src/tools/lib/all-platforms.ts
+++ b/src/tools/lib/all-platforms.ts
@@ -1,4 +1,3 @@
-// All platforms available for the platform picker.
export type Platform = 'mac' | 'windows' | 'linux'
export const allPlatforms: Platform[] = ['mac', 'windows', 'linux']
diff --git a/src/tools/lib/all-tools.ts b/src/tools/lib/all-tools.ts
index db932c91334c..e6dc50beebea 100644
--- a/src/tools/lib/all-tools.ts
+++ b/src/tools/lib/all-tools.ts
@@ -1,26 +1,16 @@
-// Maps each tool identifier to its display name.
export interface ToolsMapping {
[key: string]: string
}
-/*
- All the tools available for the Tool Picker
-
- Ordered by usage analytics to prioritize most-used tools in the tool switcher.
- This ensures popular tools appear before the "More" menu in the UnderlineNav component.
-
- Analytics Query (KQL):
- ```
- docs_v0_preference_event
- | where timestamp between (ago(180d) .. now())
- | where context.hostname == 'docs.github.com'
- | where abs(totimespan(context.created - timestamp)) < 1h // bot filter
- | summarize Count=count() by Name=preference_name, Value=preference_value
- | order by Count desc
- ```
-
- Data as of 2025-11-04 (180-day window)
-*/
+// Tools are ordered by usage analytics so common options appear before the More menu.
+// Retune with this Kusto Query Language (KQL):
+// docs_v0_preference_event
+// | where timestamp between (ago(180d) .. now())
+// | where context.hostname == 'docs.github.com'
+// | where abs(totimespan(context.created - timestamp)) < 1h // bot filter
+// | summarize Count=count() by Name=preference_name, Value=preference_value
+// | order by Count desc
+// The trailing comments show counts from a 180-day window ending 2025-11-04.
export const allTools: ToolsMapping = {
vscode: 'Visual Studio Code', // 310,824
jetbrains: 'JetBrains IDEs', // 306,982
diff --git a/src/tools/scripts/liquid-markdown-tables/convert.ts b/src/tools/scripts/liquid-markdown-tables/convert.ts
index eaf95e25050e..5bc6a2373a32 100644
--- a/src/tools/scripts/liquid-markdown-tables/convert.ts
+++ b/src/tools/scripts/liquid-markdown-tables/convert.ts
@@ -1,4 +1,4 @@
-// See the comment at the top of index.ts for how to use this script.
+// Run with npm run liquid-markdown-tables -- convert content/path/to/article.md.
import fs from 'fs'
import chalk from 'chalk'
diff --git a/src/tools/scripts/liquid-markdown-tables/index.ts b/src/tools/scripts/liquid-markdown-tables/index.ts
index 04b093a4125b..7c4883a45953 100644
--- a/src/tools/scripts/liquid-markdown-tables/index.ts
+++ b/src/tools/scripts/liquid-markdown-tables/index.ts
@@ -1,47 +1,13 @@
-/**
- * This script helps you rewrite Markdown files that might contain
- * tables with Liquid `ifversion` tags the old/wrong way.
- * For example:
- *
- * | Header | Header 2 |
- * |--------|----------|
- * | bla | bla |{% ifversion dependency-review-action-licenses %}
- * | foo | foo |{% endif %}{% ifversion dependency-review-action-fail-on-scopes %}
- * | bar | bar |{% endif %}
- * | baz | baz |
- * {%- ifversion dependency-review-action-licenses %}
- * | qux | qux |{% endif %}
- *
- * Will become:
- *
- * | Header | Header 2 |
- * |--------|----------|
- * | bla | bla |
- * | {% ifversion dependency-review-action-licenses %} |
- * | foo | foo |
- * | {% endif %} |
- * | {% ifversion dependency-review-action-fail-on-scopes %} |
- * | bar | bar |
- * | {% endif %} |
- * | baz | baz |
- * | {% ifversion dependency-review-action-licenses %} |
- * | qux | qux |
- * | {% endif %} |
- *
- * Run the script like this:
- *
- * npm run liquid-markdown-tables -- convert content/path/to/article.md
- * git diff
- *
- * To *find* files that you *can* convert, use:
- *
- * npm run liquid-markdown-tables -- find
- * # or
- * npm run liquid-markdown-tables -- find --filter content/mydocset
- *
- * This will print out paths to files that most likely contain the old/wrong Liquid `ifversion` tags.
- *
- */
+// Finds and converts Markdown tables that place Liquid ifversion tags inside table rows.
+// Example input: | foo | bar |{% ifversion dependency-review-action-licenses %}
+// Example output:
+// | foo | bar |
+// | {% ifversion dependency-review-action-licenses %} |
+// Run convert: npm run liquid-markdown-tables -- convert content/path/to/article.md
+// Then run git diff to inspect changes.
+// Run find: npm run liquid-markdown-tables -- find
+// Run filtered find: npm run liquid-markdown-tables -- find --filter content/mydocset
+// Find prints paths that likely contain misplaced Liquid ifversion tags.
import { program } from 'commander'
diff --git a/src/tools/scripts/liquid-markdown-tables/lib.ts b/src/tools/scripts/liquid-markdown-tables/lib.ts
index ec15b03812d0..d98ace258ef6 100644
--- a/src/tools/scripts/liquid-markdown-tables/lib.ts
+++ b/src/tools/scripts/liquid-markdown-tables/lib.ts
@@ -1,7 +1,7 @@
-// E.g. `{%- ifversion dependency-review-action-licenses %}\n`
+// Matches a standalone ifversion line, such as {%- ifversion dependency-review-action-licenses %}.
const ifVersionRegex = /^{%-?\s*ifversion\s+([\w- ]+)\s*-?%}\n/
const ifVersionEndRegex = /\|({%-?\s*ifversion\s+([\w- ]+)\s*-?%})\n/
-// E.g. `... |{% endif %}{% ifversion dependency-review-action-fail-on-scopes %}\n`
+// Matches a row ending in endif plus ifversion, such as |{% endif %}{% ifversion foo %}.
const endifIfVersionRegex = /\|({%-?\s*endif\s*%})({%-?\sifversion\s+([\w- ]+)\s*-?%})\n/
const endifRegex = /\|({%-?\s*endif\s*%})\n/
const endifAloneRegex = /^({%-?\s*endif\s*%})\n/
@@ -40,7 +40,7 @@ export async function processFile(content: string) {
inTable = false
}
if (inTable) {
- // E.g. `{%- ifversion dependency-review-action-licenses %}\n`
+ // Standalone ifversion tags become their own table rows.
if (ifVersionRegex.test(line)) {
const better = line.replace('{%-', '{%').replace('-%}', '%}').trim()
line = `| ${better} |\n`
diff --git a/src/types/eslint-plugins.d.ts b/src/types/eslint-plugins.d.ts
index 9c948f7ae537..9b6879007196 100644
--- a/src/types/eslint-plugins.d.ts
+++ b/src/types/eslint-plugins.d.ts
@@ -1,4 +1,4 @@
-// Type declarations for ESLint plugins without official TypeScript definitions
+// These ESLint plugins do not ship TypeScript definitions.
declare module 'eslint-plugin-github' {
import type { ESLint, Linter } from 'eslint'
diff --git a/src/types/index.ts b/src/types/index.ts
index ad447b150f48..742f7ff3ffa2 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -1,2 +1,2 @@
-// Kept so existing `@/types` imports keep working.
+// Keep this barrel so existing @/types imports keep working.
export * from './types'
diff --git a/src/types/primer__octicons.d.ts b/src/types/primer__octicons.d.ts
index d5f2a11788a9..a829595b712e 100644
--- a/src/types/primer__octicons.d.ts
+++ b/src/types/primer__octicons.d.ts
@@ -28,7 +28,7 @@ declare module '@primer/octicons' {
const octicons: {
[iconName: string]: Octicon
- // Common icons (non-exhaustive list for better autocomplete)
+ // This non-exhaustive list improves autocomplete for common icons.
alert: Octicon
check: Octicon
'check-circle': Octicon
diff --git a/src/types/types.ts b/src/types/types.ts
index f7553da5a49e..0b1ff39d964d 100644
--- a/src/types/types.ts
+++ b/src/types/types.ts
@@ -16,8 +16,7 @@ export interface ResolvedArticle {
category: string[]
}
-// Middleware attaches things to the Request, like `req.context`.
-// This type collects everything we add.
+// ExtendedRequest collects properties middleware attaches to Request, including req.context.
export type ExtendedRequest = Request & {
pagePath?: string
context?: Context
@@ -27,9 +26,9 @@ export type ExtendedRequest = Request & {
FailBot?: Failbot
}
-// Hand-maintained to match `schema` in frame/lib/frontmatter.ts.
-// Generating it from the AJV schema would need extra build tooling,
-// and the schema is built dynamically with version-specific properties.
+// Hand-maintained to match schema in frame/lib/frontmatter.ts.
+// Generating it from the AJV schema would need extra build tooling because
+// the schema is built dynamically with version-specific properties.
export type PageFrontmatter = {
title: string
versions: FrontmatterVersions
@@ -112,7 +111,7 @@ type Redirects = {
}
export type Context = {
- // Allows dynamic properties like features & version shortnames as keys
+ // Context allows dynamic keys for features and version short names.
[key: string]: unknown
currentCategory?: string
currentJourneyTrack?: JourneyContext | null
@@ -428,8 +427,8 @@ export type AllVersions = {
[name: string]: Version
}
-// Cast `req.query` to this when building URLSearchParams.
-// Without it TypeScript reports an error that can't actually happen at runtime.
+// Cast req.query to this type when building URLSearchParams.
+// TypeScript rejects values that are safe at runtime.
export type URLSearchParamsTypes = string | string[][] | Record<string, string> | URLSearchParams
export type FeatureData = {
@@ -439,7 +438,7 @@ export type Versions = {
versions: FrontmatterVersions
}
-// For parsing .md frontmatter. Not the full set the schema allows.
+// Fields parsed from .md frontmatter; the full schema allows more fields.
export type MarkdownFrontmatter = {
title: string
shortTitle?: string
, and that paragraph already carries the 16px
-// rhythm margin. The `mt-3` utility then stacks a second 16px inside it, so the
-// button ends up 32px below the preceding line but only 16px above the next one.
-// Drop the utility when the button is alone in its paragraph and let the
-// paragraph margin do the spacing, which puts the CTA on the same rhythm as
-// every other block. `!important` is required because Primer's spacing
-// utilities are themselves !important.
-//
-// `:only-child` is doing real work here — it is what keeps the two cases apart:
-// - CTA callouts (`product:`/`permissions:` frontmatter) put the button after
-// a .
+ // Brand Card renders titles as h3 Card.Heading links and intros as Card.Description paragraphs.
const titleLink = firstCard.locator('h3 a')
await expect(titleLink).toBeVisible()
@@ -1858,8 +1660,6 @@ test.describe('LandingArticleGridWithFilter component', () => {
const introText = await intro.textContent()
expect(introText).toBeTruthy()
- // Card should have categories, title, and intro, just check the card has
- // some text
const cardText = await firstCard.textContent()
expect(cardText).toBeTruthy()
expect(cardText!.length).toBeGreaterThan(0)
@@ -1868,27 +1668,23 @@ test.describe('LandingArticleGridWithFilter component', () => {
test('category filtering works correctly', async ({ page }) => {
await page.goto('/get-started/article-grid-discovery')
- // Check that category dropdown button exists and is clickable
const categoryDropdown = page.getByRole('button').filter({ hasText: 'All categories' })
await expect(categoryDropdown).toBeVisible()
- // Initially should show all articles (4 total in our fixtures)
+ // The fixture starts with four articles.
const articleGrid = page.getByTestId('article-grid')
await expect(articleGrid).toBeVisible()
const allArticleCards = articleGrid.getByTestId('article-card')
await expect(allArticleCards).toHaveCount(4)
- // Click the dropdown and the 'Testing' category
await categoryDropdown.click()
const testingOption = page.getByText('Testing', { exact: true }).last()
await expect(testingOption).toBeVisible()
await testingOption.click()
- // After filtering by Testing category, should show only 1 article based
- // on our fixtures.
+ // Filtering by Testing leaves one fixture article.
await expect(allArticleCards).toHaveCount(1)
- // Verify the filtered article contains "Testing" somewhere in its markup
const remainingCard = allArticleCards.first()
await expect(remainingCard).toContainText('Testing')
})
@@ -1899,18 +1695,17 @@ test.describe('LandingArticleGridWithFilter component', () => {
const searchInput = page.getByPlaceholder('Search articles')
await expect(searchInput).toBeVisible()
- // Initially should show all articles (4 total in our fixtures)
+ // The fixture starts with four articles.
const articleGrid = page.getByTestId('article-grid')
await expect(articleGrid).toBeVisible()
const articleCards = articleGrid.getByTestId('article-card')
await expect(articleCards).toHaveCount(4)
- // Search for "Grid" - based on our fixtures, multiple articles should have "Grid" in their names
+ // Multiple fixture article names contain Grid.
await searchInput.fill('Grid')
await expect(articleCards.first()).toBeVisible()
- // Verify that the remaining articles contain "Grid" in their content
const remainingCount = await articleCards.count()
expect(remainingCount).toBeGreaterThan(0)
for (let i = 0; i < remainingCount; i++) {
@@ -1925,44 +1720,33 @@ test.describe('LandingArticleGridWithFilter component', () => {
const searchInput = page.getByPlaceholder('Search articles')
await expect(searchInput).toBeVisible()
- // Search for a term that definitely won't match any articles, should show
- // no article cards
await searchInput.fill('noSuchArticles')
const articleGrid = page.getByTestId('article-grid')
await expect(articleGrid).toBeVisible()
const articleCards = articleGrid.getByTestId('article-card')
await expect(articleCards).toHaveCount(0)
- // Should show "no articles found" message as well
const noResultsMessage = page.getByTestId('no-articles-message')
await expect(noResultsMessage).toBeVisible()
await expect(noResultsMessage).toHaveText('No articles found matching your criteria.')
})
test('responsive behavior on different screen sizes', async ({ page }) => {
- // Super basic test, just make sure the article grid is visible on
- // different viewports sizes
-
- // Test desktop view (3 columns)
await page.setViewportSize({ width: 1200, height: 800 })
await page.goto('/get-started/article-grid-discovery')
const articleGrid = page.getByTestId('article-grid')
await expect(articleGrid).toBeVisible()
- // Test tablet view (2 columns)
await page.setViewportSize({ width: 768, height: 1024 })
- await page.waitForTimeout(100) // Brief wait for responsive changes
+ await page.waitForTimeout(100)
await expect(articleGrid).toBeVisible()
- // Test mobile view (1 column)
await page.setViewportSize({ width: 375, height: 667 })
- await page.waitForTimeout(100) // Brief wait for responsive changes
+ await page.waitForTimeout(100)
await expect(articleGrid).toBeVisible()
})
test('works with bespoke landing page', async ({ page }) => {
- // Other grid tests use the discovery landing page, bespoke pages are
- // similar so just do a quick check.
await page.goto('/get-started/article-grid-bespoke')
const articleGrid = page.getByTestId('article-grid')
@@ -1970,10 +1754,7 @@ test.describe('LandingArticleGridWithFilter component', () => {
})
test('card is keyboard-navigable via Enter (client-side)', async ({ page }) => {
- // The brand Card renders a native stretched anchor; a synthetic click from
- // pressing Enter on that anchor must bubble to the card's onClick handler so
- // keyboard users get the same client-side SPA navigation as mouse users.
- // Guards against a regression if the click-intercept logic is refactored.
+ // Brand Card's stretched anchor must bubble keyboard clicks for client-side navigation.
await page.goto('/get-started/article-grid-discovery')
const articleGrid = page.getByTestId('article-grid')
@@ -1983,8 +1764,7 @@ test.describe('LandingArticleGridWithFilter component', () => {
const href = await firstCardLink.getAttribute('href')
expect(href).toBeTruthy()
- // Mark the current document so we can prove navigation was client-side
- // (no full page reload): a hard navigation would wipe this window property.
+ // A hard navigation would clear this window marker; client-side navigation preserves it.
await page.evaluate(() => {
;(window as unknown as { __spaMarker?: boolean }).__spaMarker = true
})
@@ -2000,20 +1780,16 @@ test.describe('LandingArticleGridWithFilter component', () => {
})
test('bespoke landing page does not show duplicate articles', async ({ page }) => {
- // The bespoke fixture lists individual articles AND their parent group
- // as children, which would cause duplicates without deduplication.
+ // Bespoke fixtures list articles and their parent group, so deduplication prevents duplicates.
await page.goto('/get-started/article-grid-bespoke')
const articleGrid = page.getByTestId('article-grid')
await expect(articleGrid).toBeVisible()
const articleCards = articleGrid.getByTestId('article-card')
- // There are 4 unique articles across grid-category-one (2) and grid-category-two (2).
- // Even though grid-article-one and grid-article-two are listed both individually
- // and as children of grid-category-one, they should appear only once each.
+ // Four unique articles remain after deduplicating grid-article-one and grid-article-two.
await expect(articleCards).toHaveCount(4)
- // Verify no duplicate titles by collecting all card titles
const titles: string[] = []
const count = await articleCards.count()
for (let i = 0; i < count; i++) {
@@ -2027,19 +1803,16 @@ test.describe('LandingArticleGridWithFilter component', () => {
test.describe('Non-child page resolution', () => {
test('category page with local children renders properly', async ({ page }) => {
- // The local-category has local children (local-article-one, local-article-two)
- // and an external article reference via children frontmatter
+ // local-category mixes local-article-one, local-article-two, and an external frontmatter child.
await page.goto('/get-started/non-child-resolution/local-category')
- // Should have a title
await expect(page).toHaveTitle(/Local category test/)
- // The page should load without errors and have main content
await expect(page.locator('main')).toBeVisible()
})
test('cross-product children page loads correctly', async ({ page }) => {
- // The articles-only fixture now uses /content/ prefix in children for cross-product paths
+ // The articles-only fixture prefixes cross-product children with /content/.
await page.goto('/get-started/non-child-resolution/articles-only')
await expect(page).toHaveTitle(/Cross-product children test/)
@@ -2047,7 +1820,7 @@ test.describe('Non-child page resolution', () => {
})
test('children-only page with /content/ path loads correctly', async ({ page }) => {
- // The children-only fixture uses /content/ prefix for cross-product paths
+ // The children-only fixture prefixes cross-product children with /content/.
await page.goto('/get-started/non-child-resolution/children-only')
await expect(page).toHaveTitle(/Children only test/)
@@ -2062,20 +1835,19 @@ test.describe('Non-child page resolution', () => {
})
test('versioned cross-product children - fpt shows only fpt article', async ({ page }) => {
- // In fpt version, only the only-fpt article should be available
+ // In fpt, only only-fpt is available.
await page.goto('/get-started/non-child-resolution/versioned-cross-product')
await expect(page).toHaveTitle(/Versioned cross-product test/)
await expect(page.locator('main')).toBeVisible()
- // Check TOC has the fpt-only article
const tocLinks = page.locator('[data-testid="table-of-contents"] a')
await expect(tocLinks).toHaveCount(1)
await expect(tocLinks.first()).toHaveAttribute('href', /only-fpt/)
})
test('versioned cross-product children - ghec shows ghec articles', async ({ page }) => {
- // In ghec version, only-ghec and only-ghec-and-ghes should be available
+ // In ghec, only-ghec and only-ghec-and-ghes are available.
await page.goto(
'/enterprise-cloud@latest/get-started/non-child-resolution/versioned-cross-product',
)
@@ -2083,58 +1855,46 @@ test.describe('Non-child page resolution', () => {
await expect(page).toHaveTitle(/Versioned cross-product test/)
await expect(page.locator('main')).toBeVisible()
- // Check TOC has ghec articles (only-ghec and only-ghec-and-ghes)
const tocLinks = page.locator('[data-testid="table-of-contents"] a')
await expect(tocLinks).toHaveCount(2)
})
test('cross-product children excluded from sidebar in Japanese translation', async ({ page }) => {
- // The Japanese translation should work with cross-product children
+ // Japanese translations work with cross-product children.
await page.goto('/ja/get-started/non-child-resolution')
- // Verify page loads correctly with Japanese site context
- // Note: The title may not be fully translated in test fixtures, but the page should render
+ // Fixture titles can be partly untranslated, but Japanese site context must render.
await expect(page).toHaveTitle(/GitHub Docs/)
await expect(page.locator('main')).toBeVisible()
-
- // Verify page loads correctly - the cross-product children don't prevent the page from working
- // The detailed sidebar filtering is tested by the survey test which verifies no duplicate entries
})
})
test.describe('copy as markdown button', () => {
- // The article-body fetch backing this button is served for this fixture page
- // (see src/fixtures/tests/api-article-body.ts), so the copy path succeeds.
+ // api-article-body.ts serves this fixture's article-body fetch, so the copy path succeeds.
const articlePath = '/en/get-started/start-your-journey/api-article-body-test-page'
test('shows a checkmark after a successful copy', async ({ page, context }) => {
- // The click handler writes the article markdown to the clipboard.
await context.grantPermissions(['clipboard-read', 'clipboard-write'])
await page.goto(articlePath)
await turnOffExperimentsInPage(page)
- // `exact` matters: accessible-name matching is substring-based, so a bare
- // 'Copy markdown' also matches the code-block copy buttons that articles
- // with a ```markdown fence render ('Copy Markdown code to clipboard').
+ // Accessible-name matching treats names as substrings, so exact avoids code-block copy buttons.
const copyButton = page.getByRole('button', { name: 'Copy markdown', exact: true })
await expect(copyButton).toHaveCount(1)
await expect(copyButton).toBeVisible()
- // At rest the button is text-only — no icon at all. The checkmark below is
- // purely the success state.
+ // At rest the button is text-only; the checkmark is only the success state.
await expect(copyButton.locator('svg')).toHaveCount(0)
await copyButton.click()
- // After a successful copy, a checkmark appears...
await expect(copyButton.locator('.octicon-check')).toBeVisible()
- // ...and the article markdown lands on the clipboard.
const clipboardText = await page.evaluate(() => navigator.clipboard.readText())
expect(clipboardText).toContain('About GitHub')
- // The checkmark is temporary and clears again (2s timeout).
+ // The success checkmark clears after the 2s timeout.
await expect(copyButton.locator('.octicon-check')).toHaveCount(0, { timeout: 5000 })
})
})
diff --git a/src/frame/middleware/README.md b/src/frame/middleware/README.md
index e3f8c2b279f3..63e5e757e193 100644
--- a/src/frame/middleware/README.md
+++ b/src/frame/middleware/README.md
@@ -3,3 +3,15 @@
Each file in this directory exports an Express Middleware function.
For more info, see https://expressjs.com/en/guide/using-middleware.html
+
+## Mock Virtual Assistant portal
+
+`mock-va-portal.ts` lets you test the Virtual Assistant integration without access to a staging portal. The production portal rejects `localhost:4000` because it is hardened to `https://docs.github.com`.
+
+To test locally:
+
+1. Add `SUPPORT_PORTAL_URL=http://localhost:4000` to your `.env` file.
+2. Run `npm run dev`.
+3. Navigate to a page listed in the `PagePathToVaFlowMapping` object in `ArticleContext`.
+
+This mock is not secure. Use it only for local development.
diff --git a/src/frame/middleware/abort.ts b/src/frame/middleware/abort.ts
index e9f9496578ed..0e98af463e1a 100644
--- a/src/frame/middleware/abort.ts
+++ b/src/frame/middleware/abort.ts
@@ -14,18 +14,14 @@ class AbortError extends Error {
}
export default function abort(req: ExtendedRequest, res: Response, next: NextFunction) {
- // If the client aborts the connection, send an error
req.once('aborted', () => {
- // ignore aborts from next, usually has to do with webpack-hmr
+ // Ignore _next aborts, which usually come from webpack HMR.
if (req.path.startsWith('/_next')) {
return
}
- // NOTE: Node.js will also automatically set `req.aborted = true`
const incrementTags = []
- // Be careful with depending on attributes set on the `req` because
- // under certain conditions the contextualizers might not yet have
- // had a chance to run.
+ // Request contextualizers might not run before an abort, so guard optional request fields.
if (req.pagePath) {
incrementTags.push(`path:${req.pagePath}`)
}
diff --git a/src/frame/middleware/api.ts b/src/frame/middleware/api.ts
index a7c3f1acb7ac..4eef5c90a193 100644
--- a/src/frame/middleware/api.ts
+++ b/src/frame/middleware/api.ts
@@ -23,12 +23,8 @@ router.use('/anchor-redirect', anchorRedirect)
router.use('/pagelist', pageList)
router.use('/article', article)
-// The purpose of this is for convenience to everyone who runs this code
-// base locally but don't have an Elasticsearch server locally.
-// In production, this env var is always set but perhaps in a writer's
-// local laptop, they don't have an Elasticsearch. Neither a running local
-// server or the known credentials to a remote Elasticsearch. Whenever
-// that's the case, they can just HTTP proxy to the production server.
+// Local development proxies AI Search to docs.github.com when CSE_COPILOT_ENDPOINT
+// is unset, so writers do not need a local AI Search service.
if (process.env.CSE_COPILOT_ENDPOINT || process.env.NODE_ENV === 'test') {
router.use('/ai-search', aiSearch)
} else {
@@ -52,9 +48,8 @@ if (process.env.ELASTICSEARCH_URL) {
)
}
-// We need access to specific httpOnly cookies set on github.com from the client
-// The only way to access these on the client is to fetch them from the server
-// Limit this endpoint to 1req/min because a client should only call this route once
+// Browser JavaScript cannot read github.com httpOnly cookies.
+// The server endpoint returns the staff flag that client code needs.
router.get('/cookies', (req, res) => {
noCacheControl(res)
const cookies = {
diff --git a/src/frame/middleware/block-robots.ts b/src/frame/middleware/block-robots.ts
index 298575ec9f0c..c49e8f602f98 100644
--- a/src/frame/middleware/block-robots.ts
+++ b/src/frame/middleware/block-robots.ts
@@ -4,7 +4,7 @@ import { productMap } from '@/products/lib/all-products'
import { deprecated } from '@/versions/lib/enterprise-server-releases'
const pathRegExps: RegExp[] = [
- // Disallow indexing of WIP products
+ // WIP and hidden products stay out of search indexes.
...Object.values(productMap)
.filter((product) => product.wip || product.hidden)
.map((product) => [
@@ -12,7 +12,7 @@ const pathRegExps: RegExp[] = [
...product.versions!.map((version) => new RegExp(`^/.*?${version}/${product.id}`, 'i')),
]),
- // Disallow indexing of deprecated enterprise versions
+ // Deprecated enterprise versions stay out of search indexes.
...deprecated.map((version) => [
new RegExp(`^/.*?/enterprise-server@${version}/.*?`, 'i'),
new RegExp(`^/.*?/enterprise/${version}/.*?`, 'i'),
diff --git a/src/frame/middleware/cache-control.ts b/src/frame/middleware/cache-control.ts
index b53e5ca98364..c529f64f7918 100644
--- a/src/frame/middleware/cache-control.ts
+++ b/src/frame/middleware/cache-control.ts
@@ -19,9 +19,8 @@ const ONE_DAY = 24 * ONE_HOUR
const ONE_WEEK = 7 * ONE_DAY
const ONE_YEAR = 365 * ONE_DAY
-// Return a function you can pass a Response object to and it will set the `Cache-Control` header.
-// Max age is in seconds.
-// Max age should not be greater than 31536000, per
INSIDE the prose paragraph, so there is no paragraph margin above
-// it and `mt-3` is the only thing separating it from the text.
-// - The side-by-side Yes/No `.btn-outline` pairs are two buttons in one
-// paragraph.
-// Neither is an only child, so both keep their margin.
+// A CTA button written alone in markdown, such as ,
+// becomes its own p. The p already has a 16px rhythm margin, and mt-3 adds another
+// 16px, leaving 32px below the preceding line but 16px above the next one.
+// Drop mt-3 only when the button is alone in its p; Primer spacing utilities use
+// !important too.
+// :only-child keeps CTA callouts and side-by-side Yes/No buttons unchanged. Frontmatter
+// product: and permissions: put the CTA after a br inside the prose p, so mt-3 supplies
+// its only top spacing. Yes/No .btn-outline pairs have two buttons in one p.
.markdown-body p > a.btn:only-child {
margin-top: 0 !important;
}
-// @primer/css holds `.btn` at `white-space: nowrap`, which a button cannot
-// honour and still stay inside a narrow column. The longest CTA label — "Set up
-// a trial of GitHub Enterprise Cloud", 322px — is wider than the article column
-// below a ~420px viewport and wider than the callout's text column below ~390px,
-// so the button ran past the content edge and was clipped.
+// @primer/css sets .btn to white-space: nowrap, which makes long CTA labels overflow
+// narrow columns. The longest CTA label, "Set up a trial of GitHub Enterprise Cloud",
+// measures 322px, wider than the article column below about 420px and the callout text
+// column below about 390px, so it gets clipped.
//
-// Letting the label wrap fixes it with no breakpoint to guess at. An
-// inline-block is shrink-to-fit — min(max-content, available) — so
-// `white-space: normal` changes nothing until max-content exceeds the space
-// available: at every width where the button already fits it still renders on
-// one line, byte-identical. That also makes it self-correcting for longer
-// translated labels and for the narrower column a callout gives the same button.
+// Let labels wrap instead of guessing a breakpoint. inline-block shrink-to-fit,
+// min(max-content, available), means white-space: normal changes nothing until
+// max-content exceeds the available space. Buttons that fit still render on one line,
+// and longer translations or narrower callout columns self-correct.
.markdown-body a.btn,
.permissions-statement a.btn,
.product-statement a.btn {
white-space: normal;
- // Wrapping alone orphaned the trailing octicon on a line of its own: the
- // space between the label and the icon is a valid break point, and the
- // label filled the first line exactly. Laying the button out as a flex row
- // instead lets the label wrap within itself and keeps the icon beside it,
- // vertically centred. At widths where nothing wraps the result is within a
- // pixel of the inline-block it replaces: same 17px left inset, same 21px
- // right inset, same 32px height, still one line. The `gap` below covers the
- // one thing that does change.
+ // Wrapping alone can orphan the trailing octicon because the label/icon space can break.
+ // inline-flex lets the label wrap inside itself and keeps the icon beside it, centered.
+ // When nothing wraps, this stays within a pixel of inline-block: 17px left inset,
+ // 21px right inset, 32px height, and one line. The gap below covers the one change.
display: inline-flex;
align-items: center;
- // Flex layout eats the one thing that was separating the label from the icon.
- // The markup is `Label {% octicon "link-external" %}`, and that
- // literal space does survive Liquid and the markdown pipeline as a real text
- // node — but a whitespace-only text node between two flex items is not itself
- // a flex item, so no box is generated for it and the label ends up touching
- // the icon. `gap` puts the space back.
+ // Flex removes the literal space between the label and icon. In
+ // Label {% octicon "link-external" %}, Liquid and markdown preserve the
+ // space as a text node, but a whitespace-only text node between flex items creates no
+ // box, so the label touches the icon.
//
- // 4px rather than the measured width of that space glyph, because a space is
- // font- and locale-dependent — it measures differently on two machines here —
- // while 4px is the value Primer itself already uses between a button's icon
- // and its label. The button ends up a fraction of a pixel wider than it was
- // rather than most of a space narrower, on a number the design system owns.
+ // Use 4px instead of the measured space width because the space changes by font and
+ // locale. Primer already uses 4px between a button icon and label, so this
+ // design-system value makes the button slightly wider rather than most of a space narrower.
//
- // Only the label/icon gap is restored. Primer's `.btn .octicon` also carries
- // `margin-right: 4px`, which assumes a LEADING icon and so lands outside the
- // trailing icon on these CTAs, giving them 21px of inset on the right against
- // 17px on the left. That asymmetry is what ships today, so it stays — zeroing
- // it would restyle every CTA on the site, which is a different change from
- // keeping a long label inside its column.
+ // Restore only the label/icon gap. Primer .btn .octicon also has margin-right: 4px
+ // for leading icons, which lands outside these trailing CTA icons and gives 21px right
+ // inset against 17px left. Keep that asymmetry; zeroing it would restyle every CTA.
gap: 4px;
- // The octicon is a flex item now, and flex items shrink before their container
- // overflows. Once the label wraps, the icon is the only thing left to give, so
- // the 16px glyph was rendering at 11px in a 240px callout column. It is a
- // fixed-size icon; the label is what should absorb a narrow column.
+ // The octicon is a flex item, and flex items shrink before their container overflows.
+ // Once the label wraps, the icon is the only thing left to shrink, so the 16px glyph
+ // rendered at 11px in a 240px callout column. Keep the icon fixed and let the label absorb width.
.octicon {
flex-shrink: 0;
}
diff --git a/src/content-render/stylesheets/octicon-table-optimization.scss b/src/content-render/stylesheets/octicon-table-optimization.scss
index 23d1f9af5728..777b9d30f538 100644
--- a/src/content-render/stylesheets/octicon-table-optimization.scss
+++ b/src/content-render/stylesheets/octicon-table-optimization.scss
@@ -1,5 +1,5 @@
-// Octicon table optimization for pages with hundreds of repeated icons
-// Uses CSS background images instead of inline SVGs to dramatically reduce HTML size
+// Pages with hundreds of repeated octicons use CSS background images instead of inline SVGs
+// to reduce HTML size.
$octicon-check-path: "M13.78 4.22a.75.75 0 0 1 0 1.06l-7.25 7.25a.75.75 0 0 1-1.06 0L2.22 9.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018L6 10.94l6.72-6.72a.75.75 0 0 1 1.06 0Z";
$octicon-x-path: "M3.72 3.72a.75.75 0 0 1 1.06 0L8 6.94l3.22-3.22a.749.749 0 0 1 1.275.326.749.749 0 0 1-.215.734L9.06 8l3.22 3.22a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L8 9.06l-3.22 3.22a.751.751 0 0 1-1.042-.018.751.751 0 0 1-.018-1.042L6.94 8 3.72 4.78a.75.75 0 0 1 0-1.06Z";
diff --git a/src/content-render/stylesheets/syntax-highlighting.scss b/src/content-render/stylesheets/syntax-highlighting.scss
index 30b9b9efa5ae..e7b679732af0 100644
--- a/src/content-render/stylesheets/syntax-highlighting.scss
+++ b/src/content-render/stylesheets/syntax-highlighting.scss
@@ -8,10 +8,9 @@ from https://unpkg.com/highlight.js@9.15.8/styles/github.css
.hljs {
display: block;
padding: 0.5em;
- // The block's BASE text colour — the tokens below are prettylights, which has
- // no Brand equivalent and stays on Primer deliberately, but this one is just
- // "default text" and was painting Primer's #e6edf3 inside a Brand-framed code
- // block. The `background` is inert here (markdown-overrides paints the `pre`).
+ // Use Brand's default text color for the block itself. The syntax tokens below stay
+ // on Primer prettylights because Brand has no equivalent. Inside .markdown-body, Primer
+ // paints the pre and makes pre code transparent, so this background is inert there.
color: var(--brand-color-text-default);
background: var(--color-canvas-subtle);
}
diff --git a/src/data-directory/lib/data-directory.ts b/src/data-directory/lib/data-directory.ts
index 05e7049d93a6..56da0f47a565 100644
--- a/src/data-directory/lib/data-directory.ts
+++ b/src/data-directory/lib/data-directory.ts
@@ -17,6 +17,9 @@ interface DataDirectoryResult {
[key: string]: unknown
}
+// dataDirectory uses setWith because lodash set creates arrays for numeric release-note paths.
+// Example: release-notes.enterprise-server.2-20.0 must stay an object path.
+// See https://lodash.com/docs#set.
export default function dataDirectory(
dir: string,
opts: DataDirectoryOptions = {},
@@ -38,7 +41,6 @@ export default function dataDirectory(
const data: DataDirectoryResult = {}
- // find YAML and Markdown files in the given directory, recursively
const filenames = walk(dir, { includeBasePath: true }).filter((filename: string) => {
if (mergedOpts.ignorePatterns.some((pattern) => pattern.test(filename))) return false
@@ -51,7 +53,6 @@ export default function dataDirectory(
])
for (const [filename, fileContent] of files) {
- // derive `foo.bar.baz` object key from `foo/bar/baz.yml` filename
const key = filenameToKey(path.relative(dir, filename))
const extension = path.extname(filename).toLowerCase()
@@ -60,11 +61,6 @@ export default function dataDirectory(
processedContent = mergedOpts.preprocess(fileContent)
}
- // Add this file's data to the global data object.
- // Note we want to use `setWith` instead of `set` so we can customize the type during path creation.
- // If we just use `set`, then e.g. `release-notes.enterprise-server.2-20.0` will be an Array but
- // `release-notes.enterprise-server.3-0.0` will be an Object.
- // See https://lodash.com/docs#set for an explanation.
switch (extension) {
case '.json':
setWith(data, key, JSON.parse(processedContent), Object)
@@ -74,9 +70,7 @@ export default function dataDirectory(
break
case '.md':
case '.markdown':
- // Use `matter` to drop frontmatter, since localized reusable Markdown files
- // can potentially have frontmatter, but we want to prevent the frontmatter
- // from being rendered.
+ // Localized reusable Markdown can have frontmatter; strip it so content rendering hides it.
setWith(data, key, matter(processedContent).content, Object)
break
}
diff --git a/src/data-directory/lib/data-schemas/ctas.ts b/src/data-directory/lib/data-schemas/ctas.ts
index 2f97602bed03..31c2c0238c80 100644
--- a/src/data-directory/lib/data-schemas/ctas.ts
+++ b/src/data-directory/lib/data-schemas/ctas.ts
@@ -1,13 +1,9 @@
-// This schema enforces the structure for CTA (Call-to-Action) URL parameters
-// Used to validate CTA tracking parameters in documentation links
-
export default {
type: 'object',
additionalProperties: false,
required: ['ref_product', 'ref_type', 'ref_style'],
properties: {
- // GitHub Product: The GitHub product the CTA leads users to
- // Format: ref_product=copilot
+ // Example query parameter: ref_product=copilot.
ref_product: {
type: 'string',
name: 'Product',
@@ -26,8 +22,7 @@ export default {
],
},
- // Type of CTA: The type of action the CTA encourages users to take
- // Format: ref_type=trial
+ // Example query parameter: ref_type=trial.
ref_type: {
type: 'string',
name: 'Type',
@@ -35,8 +30,7 @@ export default {
enum: ['trial', 'purchase', 'engagement'],
},
- // CTA style: The way we are formatting the CTA in the docs
- // Format: ref_style=button
+ // Example query parameter: ref_style=button.
ref_style: {
type: 'string',
name: 'Style',
@@ -44,8 +38,7 @@ export default {
enum: ['button', 'text'],
},
- // Type of plan (Optional): For links to sign up for or trial a plan, the specific plan we link to
- // Format: ref_plan=business
+ // Example query parameter: ref_plan=business.
ref_plan: {
type: 'string',
name: 'Plan',
diff --git a/src/data-directory/lib/data-schemas/features.ts b/src/data-directory/lib/data-schemas/features.ts
index 1b9aa310350b..de81e35ff109 100644
--- a/src/data-directory/lib/data-schemas/features.ts
+++ b/src/data-directory/lib/data-schemas/features.ts
@@ -15,7 +15,6 @@ interface FeatureVersionsSchema {
additionalProperties: false
}
-// Copy the properties from the frontmatter schema.
const featureVersions: FeatureVersionsSchema = {
type: 'object',
properties: {
@@ -24,8 +23,7 @@ const featureVersions: FeatureVersionsSchema = {
additionalProperties: false,
}
-// Remove the feature versions properties.
-// We don't want to allow features within features! We just want pure versioning.
+// Each data/features file allows version gates but not nested feature gates.
delete (featureVersions.properties.versions.properties as RecordTOC for {{ allVersions[currentVersion].versio
{% for l1 in productPage.childPages %}
diff --git a/src/early-access/middleware/early-access-links.ts b/src/early-access/middleware/early-access-links.ts
index a09dfdc939f5..b9ac7d0f7cbd 100644
--- a/src/early-access/middleware/early-access-links.ts
+++ b/src/early-access/middleware/early-access-links.ts
@@ -8,13 +8,11 @@ export default function earlyAccessContext(
res: Response,
next: NextFunction,
) {
- // Use req.pagePath instead of req.path because req.path is the path
- // normalized after "converting" that `/_next/data/...` path to the
- // equivalent path if it had *not* been a client-side routing fetch.
+ // handleNextDataPath sets converted routes in req.pagePath; req.path keeps the /_next/data URL.
const url = req.pagePath!.split('/').slice(2)
if (
!(
- // Is it `/early-access` or `/enterprise-cloud@latest/early-access`?
+ // Match /early-access and versioned /early-access routes.
(
(url.length === 2 && url[1] === 'early-access') ||
(url.length === 1 && url[0] === 'early-access')
@@ -45,7 +43,7 @@ export default function earlyAccessContext(
.sort()
.map((permalink) => `- [${permalink.title}](${permalink.href})`)
- // Only read by the separate EA repo, in local development.
+ // Only the separate early access repo reads this, in local development.
req.context.earlyAccessPageLinks = earlyAccessPageLinks.length
? earlyAccessPageLinks.join('\n')
: '_None for this version!_'
diff --git a/src/early-access/scripts/clone-locally b/src/early-access/scripts/clone-locally
index ab816c586dba..4564e5f83a04 100755
--- a/src/early-access/scripts/clone-locally
+++ b/src/early-access/scripts/clone-locally
@@ -5,7 +5,6 @@
set -e
-# Go up a directory
pushd .. > /dev/null
if [ -d "docs-early-access" ]; then
@@ -14,13 +13,10 @@ if [ -d "docs-early-access" ]; then
exit 0
fi
-# Clone the repo
git clone https://github.com/github/docs-early-access.git
-# Go back to the previous working directory
popd > /dev/null
-# Symlink the local docs-early-access repo into this repo
npm run symlink-from-local-repo -- -p ../docs-early-access
echo -e '\nDone!'
diff --git a/src/early-access/scripts/create-branch b/src/early-access/scripts/create-branch
index c5f6fb6fad46..456e98db95ae 100755
--- a/src/early-access/scripts/create-branch
+++ b/src/early-access/scripts/create-branch
@@ -5,7 +5,6 @@
set -e
-# Get current branch name
currentBranch=$(git rev-parse --abbrev-ref HEAD)
if [ $currentBranch == "main" ]; then
@@ -13,7 +12,6 @@ if [ $currentBranch == "main" ]; then
exit 0
fi
-# Go up a directory
pushd .. > /dev/null
if [ ! -d "docs-early-access" ]; then
@@ -22,17 +20,13 @@ if [ ! -d "docs-early-access" ]; then
exit 0
fi
-# Navigate to docs-early-access
cd docs-early-access
-# Check out main and update
git checkout main
git pull origin main
-# Create a branch with the current docs-internal branch name
git checkout -b $currentBranch
-# Go back to the previous working directory
popd > /dev/null
echo -e "\nDone! Created a branch called ${currentBranch}. Remember to commit your work in ../docs-early-access when you're ready."
diff --git a/src/early-access/scripts/merge-early-access.sh b/src/early-access/scripts/merge-early-access.sh
index 8c70e549dc4c..00df810ca60d 100755
--- a/src/early-access/scripts/merge-early-access.sh
+++ b/src/early-access/scripts/merge-early-access.sh
@@ -1,10 +1,6 @@
#!/usr/bin/env bash
-# [start-readme]
-#
-# This script takes docs-early-access files and merges them into docs-internal
-#
-# [end-readme]
+# Merges docs-early-access files into docs-internal.
mv docs-early-access/assets/images assets/images/early-access
mv docs-early-access/content content/early-access
diff --git a/src/early-access/scripts/migrate-early-access-product.ts b/src/early-access/scripts/migrate-early-access-product.ts
index ef7e6cf2ae6f..0dbedc8430ea 100644
--- a/src/early-access/scripts/migrate-early-access-product.ts
+++ b/src/early-access/scripts/migrate-early-access-product.ts
@@ -1,8 +1,4 @@
-// [start-readme]
-//
-// Move the files from an early-access product level docs set into an existing product.
-//
-// [end-readme]
+// Moves a product-level early access docs set into an existing product.
import fs from 'fs'
import path from 'path'
@@ -54,7 +50,7 @@ if (!filesToMigrate.length) {
const migratePath: string = path.posix.join(contentDir, newPathId)
-// Update the image and data refs in the to-be-migrated early access files BEFORE moving them.
+// Rewrite early access image and data refs before moving files.
try {
execFileSync('tsx', [
'src/early-access/scripts/update-data-and-image-paths.ts',
@@ -71,7 +67,7 @@ const variablesToMove: string[] = []
const reusablesToMove: string[] = []
const imagesToMove: string[] = []
-// Add redirects to and update frontmatter in the to-be-migrated early access files BEFORE moving them.
+// Apply redirects and frontmatter changes before moving files.
for (const filepath of filesToMigrate) {
const { content, data } = frontmatter(fs.readFileSync(filepath, 'utf8'))
const redirectString: string = filepath
@@ -86,7 +82,6 @@ for (const filepath of filesToMigrate) {
fs.writeFileSync(filepath, frontmatter.stringify(content || '', data))
}
- // Find the data files and images referenced in the early access files so we can move them over.
const dataRefs: string[] = content ? content.match(patterns.dataReference) || [] : []
const variables: string[] = dataRefs.filter((ref) => ref.includes('variables'))
const reusables: string[] = dataRefs.filter((ref) => ref.includes('reusables'))
@@ -97,7 +92,6 @@ for (const filepath of filesToMigrate) {
imagesToMove.push(...images)
}
-// Move the data files and images.
for (const varRef of Array.from(new Set(variablesToMove))) {
moveVariable(varRef)
}
@@ -108,10 +102,8 @@ for (const imageRef of Array.from(new Set(imagesToMove))) {
moveImage(imageRef)
}
-// Move the content files.
execFileSync('mv', [oldPath, migratePath])
-// Update the parent product TOC with the new child path.
const parentProductTocPath: string = path.posix.join(path.dirname(newPath), 'index.md')
const parentProductToc = frontmatter(fs.readFileSync(parentProductTocPath, 'utf-8'))
if (parentProductToc.data && Array.isArray(parentProductToc.data.children)) {
@@ -123,7 +115,6 @@ fs.writeFileSync(
frontmatter.stringify(parentProductToc.content || '', parentProductToc.data || {}),
)
-// Optionally, update the new product TOC with the new title.
if (program.opts().newTitle) {
const productTocPath: string = path.posix.join(newPath, 'index.md')
const productToc = frontmatter(fs.readFileSync(productTocPath, 'utf-8'))
@@ -137,7 +128,6 @@ if (program.opts().newTitle) {
)
}
-// Update internal links now that the files have been moved.
console.log('\nRunning script to update internal links...')
execFileSync('tsx', ['src/links/scripts/update-internal-links.ts'])
@@ -153,18 +143,15 @@ Please review all the changes in docs-internal and docs-early-access, especially
`)
function moveVariable(dataRef: string): void {
- // Get the data filepath from the data reference,
- // where the data reference looks like: {% data variables.foo.bar %}
- // and the data filepath looks like: data/variables/foo.yml with key of 'bar'.
+ // Variable refs like {% data variables.foo.bar %} map to data/variables/foo.yml plus key bar.
const variablePathArray: string[] =
dataRef
.match(/{% (?:data|indented_data_reference) (.*?) %}/)?.[1]
.split('.')
- // If early access is part of the path, remove it (since the path below already includes it)
+ // Remove early-access because the path already joins under data/early-access.
.filter((n) => n !== 'early-access') || []
- // In `variables.foo.bar` the last segment is the variable key.
- // Pop it off, leaving the filepath `variables/foo.yml`.
+ // The last segment is the variable key; the remaining segments form variables/foo.yml.
const variableKey: string = last(variablePathArray) as string
variablePathArray.pop()
@@ -218,14 +205,12 @@ function moveVariable(dataRef: string): void {
}
function moveReusable(dataRef: string): void {
- // Get the data filepath from the data reference,
- // where the data reference looks like: {% data reusables.foo.bar %}
- // and the data filepath looks like: data/reusables/foo/bar.md.
+ // Reusable refs like {% data reusables.foo.bar %} map to data/reusables/foo/bar.md.
const reusablePath: string =
dataRef
.match(/{% (?:data|indented_data_reference) (\S*?) .*%}/)?.[1]
.split('.')
- // If early access is part of the path, remove it (since the path below already includes it)
+ // Remove early-access because the path already joins under data/early-access.
.filter((n) => n !== 'early-access')
.join('/') || ''
@@ -254,7 +239,7 @@ function moveReusable(dataRef: string): void {
function moveImage(imageRef: string): void {
const imagePath: string = imageRef
.replace('/assets/images/', '')
- // If early access is part of the path, remove it (since the path below already includes it)
+ // Remove early-access because the path already joins under assets/images/early-access.
.replace('early-access', '')
const oldImagePath: string = path.posix.join(
diff --git a/src/early-access/scripts/symlink-from-local-repo.ts b/src/early-access/scripts/symlink-from-local-repo.ts
index 43ef6423ec9c..59040f0a295b 100644
--- a/src/early-access/scripts/symlink-from-local-repo.ts
+++ b/src/early-access/scripts/symlink-from-local-repo.ts
@@ -1,7 +1,5 @@
-/**
- * @purpose Writer tool
- * @description Create or destroy symlinks to your local docs-early-access checkout
- */
+// @purpose Writer tool
+// @description Create or destroy symlinks to your local docs-early-access checkout
import fs from 'fs'
import path from 'path'
@@ -64,7 +62,6 @@ const destinationDirsMap: Record
(Card.Heading) wrapping a stretched , so target the heading.
+ // Brand Card renders each card title as h3 Card.Heading around a stretched link.
const items = page.locator('[data-testid="carousel-items"]')
const cardHeadings = items.locator('h3')
await expect(cardHeadings.first()).toBeVisible()
- // Verify cards have real titles (not "Unknown Article" when article not found)
await expect(cardHeadings.first()).not.toHaveText('Unknown Article')
})
@@ -1477,15 +1320,13 @@ test.describe('LandingCarousel component', () => {
const carousel = page.locator('[data-testid="landing-carousel"]')
await expect(carousel).toBeVisible()
- // Should show 3 cards on desktop
const cards = carousel.locator('a')
await expect(cards).toHaveCount(3)
- // Check for navigation buttons if there are more than 3 articles
const nextButton = carousel.getByRole('button', { name: 'Next articles' })
if (await nextButton.isVisible()) {
const prevButton = carousel.getByRole('button', { name: 'Previous articles' })
- await expect(prevButton).toBeDisabled() // Should be disabled on first page
+ await expect(prevButton).toBeDisabled()
await expect(nextButton).toBeEnabled()
}
})
@@ -1497,7 +1338,6 @@ test.describe('LandingCarousel component', () => {
const carousel = page.locator('[data-testid="landing-carousel"]')
await expect(carousel).toBeVisible()
- // Should show 1 card on mobile
const cards = carousel.locator('a')
await expect(cards).toHaveCount(1)
})
@@ -1507,36 +1347,32 @@ test.describe('Multi-carousel support', () => {
test('displays multiple carousels from carousels frontmatter', async ({ page }) => {
await page.goto('/get-started/multi-carousel')
- // Should have multiple carousels rendered
const carousels = page.locator('[data-testid="landing-carousel"]')
const carouselCount = await carousels.count()
- // We defined exactly 2 carousels in the frontmatter
+ // Frontmatter defines exactly two carousels.
expect(carouselCount).toBe(2)
})
test('carousel with matching ui.yml key displays translated title', async ({ page }) => {
await page.goto('/get-started/multi-carousel')
- // The "recommended" carousel should show "Recommended" title from ui.yml
+ // The recommended carousel title comes from ui.yml.
const carouselHeadings = page.locator('[data-testid="landing-carousel"] h2')
const headingTexts = await carouselHeadings.allTextContents()
- // Check that at least one heading has "Recommended"
expect(headingTexts.some((text) => text.includes('Recommended'))).toBe(true)
})
test('carousel without matching ui.yml key renders without title', async ({ page }) => {
await page.goto('/get-started/multi-carousel')
- // The "titleTwoNoMatchingUiYml" carousel should not have a visible heading
- // or the heading element should be empty/not exist for that carousel
+ // A carousel without a matching ui.yml key has no heading element.
const carouselHeadings = page.locator('[data-testid="landing-carousel"] h2')
const headingTexts = await carouselHeadings.allTextContents()
- // The raw key "titleTwoNoMatchingUiYml" should NOT appear as a heading
- // (the component should not show the key as fallback)
+ // titleTwoNoMatchingUiYml must not render as a fallback heading.
expect(headingTexts.some((text) => text === 'titleTwoNoMatchingUiYml')).toBe(false)
})
@@ -1546,10 +1382,8 @@ test.describe('Multi-carousel support', () => {
const carousels = page.locator('[data-testid="landing-carousel"]')
const count = await carousels.count()
- // We have 2 carousels: "recommended" and "titleTwoNoMatchingUiYml"
expect(count).toBe(2)
- // Count carousels that have h2 elements
let carouselsWithHeadings = 0
for (let i = 0; i < count; i++) {
const carousel = carousels.nth(i)
@@ -1559,11 +1393,9 @@ test.describe('Multi-carousel support', () => {
}
}
- // Only 1 carousel should have a heading (recommended has ui.yml entry)
- // titleTwoNoMatchingUiYml should NOT have an h2 element at all
+ // Only recommended has a ui.yml entry, so titleTwoNoMatchingUiYml must not render an h2.
expect(carouselsWithHeadings).toBe(1)
- // Verify the specific titles that should be visible
const visibleHeadings = await carousels.locator('h2').allTextContents()
expect(visibleHeadings).toContain('Recommended')
expect(visibleHeadings).not.toContain('titleTwoNoMatchingUiYml')
@@ -1575,7 +1407,6 @@ test.describe('Multi-carousel support', () => {
const carousels = page.locator('[data-testid="landing-carousel"]')
const count = await carousels.count()
- // Each carousel should have at least one article
for (let i = 0; i < count; i++) {
const carousel = carousels.nth(i)
const articles = carousel.locator('[data-testid="carousel-items"] a')
@@ -1592,14 +1423,12 @@ test.describe('Journey Tracks', () => {
const journeyTracks = page.locator('[data-testid="journey-tracks"]')
await expect(journeyTracks).toBeVisible()
- // Check that at least one track is displayed
const tracks = page.locator('[data-testid="journey-track"]')
await expect(tracks.first()).toBeVisible()
- // Verify track has proper structure
const firstTrack = tracks.first()
- await expect(firstTrack.locator('h2')).toBeVisible() // Track title
- await expect(firstTrack.locator('p')).toBeVisible() // Track description
+ await expect(firstTrack.locator('h2')).toBeVisible()
+ await expect(firstTrack.locator('p')).toBeVisible()
})
test('track expansion and collapse functionality', async ({ page }) => {
@@ -1608,7 +1437,6 @@ test.describe('Journey Tracks', () => {
const firstTrack = page.locator('[data-testid="journey-track"]').first()
const expandButton = firstTrack.locator('summary')
- // Initially collapsed
const articlesList = firstTrack.locator('[data-testid="journey-articles"]')
await expect(articlesList).not.toBeVisible()
@@ -1630,7 +1458,6 @@ test.describe('Journey Tracks', () => {
await expandButton.click()
- // Click on first article
const firstArticle = firstTrack.locator('[data-testid="journey-articles"] li a').first()
await expect(firstArticle).toBeVisible()
@@ -1646,7 +1473,7 @@ test.describe('Journey Tracks', () => {
const expandButton = firstTrack.locator('summary')
await expandButton.click()
- // article links should preserve the language and version
+ // Article links preserve language and version.
const firstArticle = firstTrack.locator('[data-testid="journey-articles"] li a').first()
const href = await firstArticle.getAttribute('href')
@@ -1659,7 +1486,6 @@ test.describe('Journey Tracks', () => {
const tracks = page.locator('[data-testid="journey-track"]')
- // Check that liquid templates are rendered (no raw template syntax visible)
const trackContent = await tracks.first().textContent()
expect(trackContent).not.toContain('{{')
expect(trackContent).not.toContain('}}')
@@ -1670,21 +1496,18 @@ test.describe('Journey Tracks', () => {
test('renders the single-track journey landing path', async ({ page }) => {
await page.goto('/get-started/test-journey-single')
- // single-track pages use the simplified heading + guide list, not the numbered cards
+ // Single-track pages render the simplified heading and guide list instead of numbered cards.
const singleTrack = page.locator('[data-testid="journey-single-track"]')
await expect(singleTrack).toBeVisible()
await expect(page.locator('[data-testid="journey-tracks"]')).toHaveCount(0)
- // heading is present
await expect(singleTrack.locator('h2')).toBeVisible()
- // guide list renders its article links
const guides = singleTrack.locator('[data-testid="journey-articles"] li a')
await expect(guides.first()).toBeVisible()
expect(await guides.count()).toBeGreaterThan(0)
- // without a surrounding card, the list must sit flush with the heading
- // rather than picking up the card's inset
+ // Without a card, the guide list sits flush with the heading instead of inheriting inset.
const listPaddingLeft = await singleTrack
.locator('[data-testid="journey-articles"]')
.evaluate((el) => getComputedStyle(el).paddingLeft)
@@ -1692,21 +1515,14 @@ test.describe('Journey Tracks', () => {
})
test('journey navigation components show on article pages', async ({ page }) => {
- // go to an article that's part of a journey track
await page.goto('/get-started/start-your-journey/hello-world')
- // The journey footer "Up next" nav should be visible. (The Docs 2026 redesign
- // removed the sidebar journey card; next-step info now lives in the bottom
- // pager + the in-panel "Up next" section.)
+ // Journey next-step info shows in the bottom pager and the right-rail Up next section.
const journeyNav = page.locator('[data-testid="journey-track-nav"]')
await expect(journeyNav).toBeVisible()
})
- // Restores the coverage the Docs 2026 migration dropped along with the sidebar
- // journey card: `alternativeNextStep` and its AUTOTITLE resolution now render
- // in the right-rail "Up next" section instead. That section rides the drawer's
- // reveal breakpoint, so it needs a viewport inside the drawer range and a
- // fixture long enough to keep the bottom pager outside the viewport.
+ // A drawer-range viewport shows alternativeNextStep and AUTOTITLE in Up next; the long fixture hides the pager.
test('up next displays branching text when present', async ({ page }) => {
await page.setViewportSize({ width: 1440, height: 900 })
await page.goto('/get-started/foo/journey-test-article')
@@ -1716,7 +1532,7 @@ test.describe('Journey Tracks', () => {
const upNext = page.getByTestId('up-next')
await expect(upNext).toBeVisible()
- // Branching text should be rendered with its markdown link resolved
+ // Branching text renders after resolving its markdown link.
await expect(upNext).toContainText('Want to skip ahead?')
await expect(upNext).not.toContainText('AUTOTITLE')
@@ -1758,7 +1574,6 @@ test.describe('Journey Tracks', () => {
const journeyNav = page.locator('[data-testid="journey-track-nav"]')
await expect(journeyNav).toBeVisible()
- // Link should display the next track's title and go to its first article
const nextTrackLink = journeyNav.locator('a').filter({ hasText: 'Advanced topics' })
await expect(nextTrackLink).toBeVisible()
@@ -1768,9 +1583,7 @@ test.describe('Journey Tracks', () => {
})
test.describe('Docs 2026 in-article navigation', () => {
- // Below the drawer's reveal breakpoint the right-rail "In this article" panel
- // is hidden and the collapsed control in the secondary bar is the ONLY
- // mini-TOC — the common case for most readers — so it needs its own coverage.
+ // Below the drawer breakpoint, the secondary-bar mini-TOC is the only in-page control.
test('the collapsed "In this article" menu navigates below the drawer breakpoint', async ({
page,
}) => {
@@ -1780,7 +1593,6 @@ test.describe('Docs 2026 in-article navigation', () => {
const subBar = page.getByTestId('overview-subbar')
await expect(subBar).toBeVisible()
- // The full drawer must not also be showing at this width.
await expect(page.getByTestId('minitoc')).toBeHidden()
await subBar.getByRole('button').click()
@@ -1794,11 +1606,7 @@ test.describe('Docs 2026 in-article navigation', () => {
expect(page.url()).toContain(href)
})
- // Regression guard. Platform/tool-gated headings stay in the DOM with the
- // `hidden` attribute, so they measure as an all-zero rect. Before
- // useActiveSection filtered by the selection, such a heading always satisfied
- // the "scrolled past" threshold, so the collapsed control could end up
- // labelled with a section belonging to a platform the reader had not chosen.
+ // useActiveSection filters hidden platform/tool headings because they have zero rects.
test('the collapsed menu is never labelled with a hidden platform section', async ({ page }) => {
await page.setViewportSize({ width: 1100, height: 900 })
await page.goto('/get-started/liquid/platform-specific?platform=windows')
@@ -1808,7 +1616,6 @@ test.describe('Docs 2026 in-article navigation', () => {
await expect(trigger).toBeVisible()
await expect(trigger).not.toContainText('Macintosh')
- // Scroll past the first heading so an active section is actually resolved.
await page.mouse.wheel(0, 2000)
await expect(trigger).not.toContainText('Macintosh')
})
@@ -1818,8 +1625,6 @@ test.describe('LandingArticleGridWithFilter component', () => {
test('displays article grid with filter controls', async ({ page }) => {
await page.goto('/get-started/article-grid-discovery')
- // Check that the main components are visible, title, categories drop
- // down, search input.
const articleGrid = page.getByTestId('article-grid')
await expect(articleGrid).toBeVisible()
@@ -1842,14 +1647,11 @@ test.describe('LandingArticleGridWithFilter component', () => {
const articleGrid = page.getByTestId('article-grid')
await expect(articleGrid).toBeVisible()
- // Check that article cards are present and they have expected structure
- // by checking the first card.
const articleCards = articleGrid.getByTestId('article-card')
await expect(articleCards.first()).toBeVisible()
const firstCard = articleCards.first()
- // Brand Card renders the title as an
(Card.Heading) wrapping a
- // stretched , and the intro as a Card.Description