Assert the OG card URL escapes proxy.ts's matcher, instead of only reporting it#13932

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
os-project-manager merged 1 commit into from
Aug 31, 2026
Merged

Assert the OG card URL escapes proxy.ts's matcher, instead of only reporting it #13932

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 92 additions & 10 deletions scripts/check-docs-locale-catch-all.mjs
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -92,10 +92,28 @@
// no type. Silent by construction, which is the same reason the catch-all guard
// above needed a gate rather than a comment.
//
// This limb asserts the half that was asserted nowhere: the URL `getPageImage()`
// builds ends in a final segment containing a dot. It deliberately does NOT
// re-assert that the matcher excludes dotted paths -- that condition is read
// once, above, and both halves are reported in the summary line.
// This limb asserts the invariant on the URL itself, from BOTH ends, because
// the two ends are one surface and either one moving breaks it:
//
// 1. the URL `getPageImage()` builds ends in a final segment containing a
// dot -- the marker side; and
// 2. that URL, compiled against the matcher `proxy.ts` carries TODAY, is not
// matched by it -- the proxy side.
//
// (2) is the direct reading, and it is what makes the conditional catch-all
// requirement below safe to keep. That requirement relaxes when dotted paths
// stop bypassing the proxy, which is correct on its own terms -- but the same
// widening 404s every `og:image`, so a gate that only read the flag could go
// ENTIRELY green on the change that breaks the whole surface: catch-all limb
// relaxed, i18n limb relaxed, and this limb still seeing a dotted marker. A
// reading that licenses a relaxation and is asserted nowhere is not a check; it
// is a statistic with a veto. So the flag keeps its licensing role and this
// limb holds the surface, measured on the built URL rather than on either side.
//
// The two are not redundant: a matcher that widened its dot exclusion but still
// excludes the `/og/` prefix relaxes the catch-all requirement AND leaves the
// cards served, and this limb correctly stays green there. It fires on the
// break, not on the flag.
//
// The assertion is made on the URL the function RETURNS, not on the array
// literal alone. The marker is the URL's final segment only while the returned
Expand DownExpand Up@@ -347,8 +365,12 @@ export function checkApp({ appDir, proxyPath, i18nPath, sourcePath }) {
// Unconditional, unlike the catch-all guard below -- a matcher that stopped
// excluding dotted paths would not relax this requirement, it would break the
// surface outright, so there is no condition under which a dotless marker is
// the right answer. The matcher half is read once above and reported, never
// re-asserted here.
// the right answer. Asserted from BOTH ends on the built URL: the marker must
// still carry a dot, AND the URL must still escape the matcher `proxy.ts`
// carries today. The second is the one the `dottedBypassesProxy` flag alone
// could never make -- the flag LICENSES relaxations below, so leaving its
// consequence for this surface unasserted is what let a widened matcher take
// every limb green at once.
if (!existsSync(sourcePath)) {
findings.push(`missing ${sourcePath}`);
} else {
Expand All@@ -371,6 +393,24 @@ export function checkApp({ appDir, proxyPath, i18nPath, sourcePath }) {
+ "final segment containing a dot in apps/docs/lib/source.ts (the marker's NAME is free; its "
+ 'dot is not).',
);
} else if (!stats.ogUrlSkipsProxy) {
// The break from the OTHER direction: the marker still carries its dot,
// but the matcher moved under it. Reported here rather than left to the
// `dottedBypassesProxy` flag, which merely relaxes two limbs below and
// asserts nothing -- the whole reason this widening could land green.
findings.push(
`the OG card URL \`${OG_BUILDER}()\` builds -- \`${probe}\` -- IS matched by proxy.ts's `
+ `matcher, even though its final segment \`${finalSegment}\` still contains a dot. The `
+ 'exclusion the marker relies on moved on the PROXY side: this URL is now locale-rewritten '
+ `to \`/<locale>${probe}\`, a path app/og/ does not serve, because that tree is top-level `
+ 'and not under app/[lang]/. Every `og:image` on the site 404s at once, and nothing fetches '
+ 'these URLs, so no other check sees it. Note this is NOT relaxed by the same widening '
+ 'relaxing the catch-all requirement below: rewriting dotted paths removes the need for the '
+ `locale guard and breaks the OG cards, both at once. Restore an exclusion in `
+ `apps/docs/proxy.ts that covers this URL -- the dot limb (\`.*\\..*\`) is what covered it, `
+ `and excluding the \`/og/\` prefix outright is the narrower alternative. Matcher(s) read: `
+ `${JSON.stringify(read.matchers)}.`,
);
}
}
}
Expand DownExpand Up@@ -545,14 +585,54 @@ function selfTest() {
assert(run.stats.segments === 2 && run.stats.guarded === 1, `both segments must be counted -- got ${summarise(run.stats)}`);

// 6. The condition is LIVE, not decorative: a matcher that DOES cover dotted
// paths makes the guard unnecessary, and the missing guard goes green.
// paths makes the locale guard unnecessary, and the missing guard is NOT
// demanded. That relaxation is kept -- it is correct on its own terms.
// What is no longer allowed is for it to be the WHOLE story: the same
// widening takes every `og:image` to 404, so the OG limb reports it here
// and the run as a whole is red. Before that limb existed this fixture
// was silent, which is the hole this case now pins from both sides.
paths = writeFixture(dir, {
proxy: `export const config = { matcher: ['/((?!api|_next/static).*)'] };\n`,
layout: FIXTURE_LAYOUT.replace(' if (!isSupportedLanguage(lang)) notFound();\n', ''),
});
run = checkApp(paths);
assert(run.findings.length === 0, `a proxy that rewrites dotted paths must not demand the guard -- got ${JSON.stringify(run.findings)}`);
assert(run.stats.dottedBypassesProxy === false, 'the widened matcher must be read as covering dotted paths');
assert(
!run.findings.some((f) => /never calls|is a top-level catch-all|does not read/.test(f)),
`a proxy that rewrites dotted paths must still not demand the locale guard -- got ${JSON.stringify(run.findings)}`,
);
assert(
run.findings.length === 1 && /IS matched by proxy\.ts's matcher/.test(run.findings[0]),
`widening the matcher must be reported by the OG limb, not left green -- got ${JSON.stringify(run.findings)}`,
);

// 6b. RED, THE ABLATION FROM THE PROXY SIDE. Nothing but the matcher moves:
// the guard is present, the marker still ends in `image.png`, every
// other limb is satisfied and the two conditional limbs have relaxed
// themselves. The surface is broken anyway, and this is the reading that
// says so -- taken from the built URL, not from either side alone.
paths = writeFixture(dir, { proxy: `export const config = { matcher: ['/((?!api|_next/static).*)'] };\n` });
run = checkApp(paths);
assert(run.stats.ogFinalSegmentDotted === true, 'the marker must be untouched in the proxy-side ablation');
assert(run.stats.ogUrlSkipsProxy === false, 'the widened matcher must be read as now covering the OG card URL');
assert(
run.findings.length === 1 && /IS matched by proxy\.ts's matcher/.test(run.findings[0]),
`a matcher that swallowed the OG card URL must be reported once -- got ${JSON.stringify(run.findings)}`,
);

// 6c. GREEN control: the limb fires on the BREAK, not on the flag. This
// matcher drops the dot exclusion -- so the catch-all requirement
// relaxes exactly as in 6 -- but still excludes the `/og/` prefix, so
// the cards are still served and there is nothing to report. A limb
// wired to `dottedBypassesProxy` instead of to the URL would cry here.
paths = writeFixture(dir, {
proxy: `export const config = { matcher: ['/((?!api|_next/static|og/).*)'] };\n`,
layout: FIXTURE_LAYOUT.replace(' if (!isSupportedLanguage(lang)) notFound();\n', ''),
});
run = checkApp(paths);
assert(run.stats.dottedBypassesProxy === false, 'the og-excluding matcher must still be read as covering dotted paths');
assert(run.stats.ogUrlSkipsProxy === true, 'an excluded `/og/` prefix must be read as still escaping the matcher');
assert(run.findings.length === 0, `a widening that still excludes /og/ must stay green -- got ${JSON.stringify(run.findings)}`);

// 7. RED: a matcher that stops rewriting the dotless probe is reported, not
// silently read as "everything bypasses".
Expand DownExpand Up@@ -625,8 +705,10 @@ function selfTest() {
`✓ check-docs-locale-catch-all --self-test: ${checked} assertions over a temp fixture (real checkApp path); `
+ 'every limb -- deleted guard, guard behind the return, hollowed predicate, a new unguarded segment, '
+ 'an uncompilable matcher, an OG marker stripped of its dot, an OG marker dropped, an OG url that '
+ 'stopped ending in its segments, a missing builder -- observed FAILING, the proxy condition observed '
+ "flipping the catch-all requirement off, and the OG marker's NAME observed free while its dot is not.",
+ 'stopped ending in its segments, a missing builder, and a matcher widened until it swallows the OG '
+ 'card URL with the marker untouched -- observed FAILING, the proxy condition observed flipping the '
+ "catch-all requirement off WITHOUT taking the run green, the OG marker's NAME observed free while "
+ 'its dot is not, and a widening that still excludes /og/ observed staying green.',
);
}

Expand Down
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
Assert the OG card URL escapes proxy.ts's matcher, instead of only reporting it#13932

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-project-manager
merged 1 commit into

from

Aug 31, 2026
 Merged


Assert the OG card URL escapes proxy.ts's matcher, instead of only reporting it
#13932
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


102 changes: 92 additions & 10 deletions
scripts/check-docs-locale-catch-all.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -92,10 +92,28 @@
// no type. Silent by construction, which is the same reason the catch-all guard
// above needed a gate rather than a comment.
//
// This limb asserts the half that was asserted nowhere: the URL `getPageImage()`
// builds ends in a final segment containing a dot. It deliberately does NOT
// re-assert that the matcher excludes dotted paths -- that condition is read
// once, above, and both halves are reported in the summary line.
// This limb asserts the invariant on the URL itself, from BOTH ends, because
// the two ends are one surface and either one moving breaks it:
//
// 1. the URL `getPageImage()` builds ends in a final segment containing a
// dot -- the marker side; and
// 2. that URL, compiled against the matcher `proxy.ts` carries TODAY, is not
// matched by it -- the proxy side.
//
// (2) is the direct reading, and it is what makes the conditional catch-all
// requirement below safe to keep. That requirement relaxes when dotted paths
// stop bypassing the proxy, which is correct on its own terms -- but the same
// widening 404s every `og:image`, so a gate that only read the flag could go
// ENTIRELY green on the change that breaks the whole surface: catch-all limb
// relaxed, i18n limb relaxed, and this limb still seeing a dotted marker. A
// reading that licenses a relaxation and is asserted nowhere is not a check; it
// is a statistic with a veto. So the flag keeps its licensing role and this
// limb holds the surface, measured on the built URL rather than on either side.
//
// The two are not redundant: a matcher that widened its dot exclusion but still
// excludes the `/og/` prefix relaxes the catch-all requirement AND leaves the
// cards served, and this limb correctly stays green there. It fires on the
// break, not on the flag.
//
// The assertion is made on the URL the function RETURNS, not on the array
// literal alone. The marker is the URL's final segment only while the returned
Expand DownExpand Up@@ -347,8 +365,12 @@ export function checkApp({ appDir, proxyPath, i18nPath, sourcePath }) {
 // Unconditional, unlike the catch-all guard below -- a matcher that stopped
 // excluding dotted paths would not relax this requirement, it would break the
 // surface outright, so there is no condition under which a dotless marker is
 // the right answer. The matcher half is read once above and reported, never
 // re-asserted here.
 // the right answer. Asserted from BOTH ends on the built URL: the marker must
 // still carry a dot, AND the URL must still escape the matcher `proxy.ts`
 // carries today. The second is the one the `dottedBypassesProxy` flag alone
 // could never make -- the flag LICENSES relaxations below, so leaving its
 // consequence for this surface unasserted is what let a widened matcher take
 // every limb green at once.
 if (!existsSync(sourcePath)) {
 findings.push(`missing ${sourcePath}`);
 } else {
Expand All@@ -371,6 +393,24 @@ export function checkApp({ appDir, proxyPath, i18nPath, sourcePath }) {
 + "final segment containing a dot in apps/docs/lib/source.ts (the marker's NAME is free; its "
 + 'dot is not).',
 );
 } else if (!stats.ogUrlSkipsProxy) {
 // The break from the OTHER direction: the marker still carries its dot,
 // but the matcher moved under it. Reported here rather than left to the
 // `dottedBypassesProxy` flag, which merely relaxes two limbs below and
 // asserts nothing -- the whole reason this widening could land green.
 findings.push(
 `the OG card URL \`${OG_BUILDER}()\` builds -- \`${probe}\` -- IS matched by proxy.ts's `
 + `matcher, even though its final segment \`${finalSegment}\` still contains a dot. The `
 + 'exclusion the marker relies on moved on the PROXY side: this URL is now locale-rewritten '
 + `to \`/<locale>${probe}\`, a path app/og/ does not serve, because that tree is top-level `
 + 'and not under app/[lang]/. Every `og:image` on the site 404s at once, and nothing fetches '
 + 'these URLs, so no other check sees it. Note this is NOT relaxed by the same widening '
 + 'relaxing the catch-all requirement below: rewriting dotted paths removes the need for the '
 + `locale guard and breaks the OG cards, both at once. Restore an exclusion in `
 + `apps/docs/proxy.ts that covers this URL -- the dot limb (\`.*\\..*\`) is what covered it, `
 + `and excluding the \`/og/\` prefix outright is the narrower alternative. Matcher(s) read: `
 + `${JSON.stringify(read.matchers)}.`,
 );
 }
 }
 }
Expand DownExpand Up@@ -545,14 +585,54 @@ function selfTest() {
 assert(run.stats.segments === 2 && run.stats.guarded === 1, `both segments must be counted -- got ${summarise(run.stats)}`);

 // 6. The condition is LIVE, not decorative: a matcher that DOES cover dotted
 // paths makes the guard unnecessary, and the missing guard goes green.
 // paths makes the locale guard unnecessary, and the missing guard is NOT
 // demanded. That relaxation is kept -- it is correct on its own terms.
 // What is no longer allowed is for it to be the WHOLE story: the same
 // widening takes every `og:image` to 404, so the OG limb reports it here
 // and the run as a whole is red. Before that limb existed this fixture
 // was silent, which is the hole this case now pins from both sides.
 paths = writeFixture(dir, {
 proxy: `export const config = { matcher: ['/((?!api|_next/static).*)'] };\n`,
 layout: FIXTURE_LAYOUT.replace(' if (!isSupportedLanguage(lang)) notFound();\n', ''),
 });
 run = checkApp(paths);
 assert(run.findings.length === 0, `a proxy that rewrites dotted paths must not demand the guard -- got ${JSON.stringify(run.findings)}`);
 assert(run.stats.dottedBypassesProxy === false, 'the widened matcher must be read as covering dotted paths');
 assert(
 !run.findings.some((f) => /never calls|is a top-level catch-all|does not read/.test(f)),
 `a proxy that rewrites dotted paths must still not demand the locale guard -- got ${JSON.stringify(run.findings)}`,
 );
 assert(
 run.findings.length === 1 && /IS matched by proxy\.ts's matcher/.test(run.findings[0]),
 `widening the matcher must be reported by the OG limb, not left green -- got ${JSON.stringify(run.findings)}`,
 );

 // 6b. RED, THE ABLATION FROM THE PROXY SIDE. Nothing but the matcher moves:
 // the guard is present, the marker still ends in `image.png`, every
 // other limb is satisfied and the two conditional limbs have relaxed
 // themselves. The surface is broken anyway, and this is the reading that
 // says so -- taken from the built URL, not from either side alone.
 paths = writeFixture(dir, { proxy: `export const config = { matcher: ['/((?!api|_next/static).*)'] };\n` });
 run = checkApp(paths);
 assert(run.stats.ogFinalSegmentDotted === true, 'the marker must be untouched in the proxy-side ablation');
 assert(run.stats.ogUrlSkipsProxy === false, 'the widened matcher must be read as now covering the OG card URL');
 assert(
 run.findings.length === 1 && /IS matched by proxy\.ts's matcher/.test(run.findings[0]),
 `a matcher that swallowed the OG card URL must be reported once -- got ${JSON.stringify(run.findings)}`,
 );

 // 6c. GREEN control: the limb fires on the BREAK, not on the flag. This
 // matcher drops the dot exclusion -- so the catch-all requirement
 // relaxes exactly as in 6 -- but still excludes the `/og/` prefix, so
 // the cards are still served and there is nothing to report. A limb
 // wired to `dottedBypassesProxy` instead of to the URL would cry here.
 paths = writeFixture(dir, {
 proxy: `export const config = { matcher: ['/((?!api|_next/static|og/).*)'] };\n`,
 layout: FIXTURE_LAYOUT.replace(' if (!isSupportedLanguage(lang)) notFound();\n', ''),
 });
 run = checkApp(paths);
 assert(run.stats.dottedBypassesProxy === false, 'the og-excluding matcher must still be read as covering dotted paths');
 assert(run.stats.ogUrlSkipsProxy === true, 'an excluded `/og/` prefix must be read as still escaping the matcher');
 assert(run.findings.length === 0, `a widening that still excludes /og/ must stay green -- got ${JSON.stringify(run.findings)}`);

 // 7. RED: a matcher that stops rewriting the dotless probe is reported, not
 // silently read as "everything bypasses".
Expand DownExpand Up@@ -625,8 +705,10 @@ function selfTest() {
 `✓ check-docs-locale-catch-all --self-test: ${checked} assertions over a temp fixture (real checkApp path); `
 + 'every limb -- deleted guard, guard behind the return, hollowed predicate, a new unguarded segment, '
 + 'an uncompilable matcher, an OG marker stripped of its dot, an OG marker dropped, an OG url that '
 + 'stopped ending in its segments, a missing builder -- observed FAILING, the proxy condition observed '
 + "flipping the catch-all requirement off, and the OG marker's NAME observed free while its dot is not.",
 + 'stopped ending in its segments, a missing builder, and a matcher widened until it swallows the OG '
 + 'card URL with the marker untouched -- observed FAILING, the proxy condition observed flipping the '
 + "catch-all requirement off WITHOUT taking the run green, the OG marker's NAME observed free while "
 + 'its dot is not, and a widening that still excludes /og/ observed staying green.',
 );
}

Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Assert the OG card URL escapes proxy.ts's matcher, instead of only reporting it#13932

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-project-manager
merged 1 commit into

from

Aug 31, 2026
 Merged


Assert the OG card URL escapes proxy.ts's matcher, instead of only reporting it
#13932
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


102 changes: 92 additions & 10 deletions
scripts/check-docs-locale-catch-all.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -92,10 +92,28 @@
// no type. Silent by construction, which is the same reason the catch-all guard
// above needed a gate rather than a comment.
//
// This limb asserts the half that was asserted nowhere: the URL `getPageImage()`
// builds ends in a final segment containing a dot. It deliberately does NOT
// re-assert that the matcher excludes dotted paths -- that condition is read
// once, above, and both halves are reported in the summary line.
// This limb asserts the invariant on the URL itself, from BOTH ends, because
// the two ends are one surface and either one moving breaks it:
//
// 1. the URL `getPageImage()` builds ends in a final segment containing a
// dot -- the marker side; and
// 2. that URL, compiled against the matcher `proxy.ts` carries TODAY, is not
// matched by it -- the proxy side.
//
// (2) is the direct reading, and it is what makes the conditional catch-all
// requirement below safe to keep. That requirement relaxes when dotted paths
// stop bypassing the proxy, which is correct on its own terms -- but the same
// widening 404s every `og:image`, so a gate that only read the flag could go
// ENTIRELY green on the change that breaks the whole surface: catch-all limb
// relaxed, i18n limb relaxed, and this limb still seeing a dotted marker. A
// reading that licenses a relaxation and is asserted nowhere is not a check; it
// is a statistic with a veto. So the flag keeps its licensing role and this
// limb holds the surface, measured on the built URL rather than on either side.
//
// The two are not redundant: a matcher that widened its dot exclusion but still
// excludes the `/og/` prefix relaxes the catch-all requirement AND leaves the
// cards served, and this limb correctly stays green there. It fires on the
// break, not on the flag.
//
// The assertion is made on the URL the function RETURNS, not on the array
// literal alone. The marker is the URL's final segment only while the returned
Expand DownExpand Up@@ -347,8 +365,12 @@ export function checkApp({ appDir, proxyPath, i18nPath, sourcePath }) {
 // Unconditional, unlike the catch-all guard below -- a matcher that stopped
 // excluding dotted paths would not relax this requirement, it would break the
 // surface outright, so there is no condition under which a dotless marker is
 // the right answer. The matcher half is read once above and reported, never
 // re-asserted here.
 // the right answer. Asserted from BOTH ends on the built URL: the marker must
 // still carry a dot, AND the URL must still escape the matcher `proxy.ts`
 // carries today. The second is the one the `dottedBypassesProxy` flag alone
 // could never make -- the flag LICENSES relaxations below, so leaving its
 // consequence for this surface unasserted is what let a widened matcher take
 // every limb green at once.
 if (!existsSync(sourcePath)) {
 findings.push(`missing ${sourcePath}`);
 } else {
Expand All@@ -371,6 +393,24 @@ export function checkApp({ appDir, proxyPath, i18nPath, sourcePath }) {
 + "final segment containing a dot in apps/docs/lib/source.ts (the marker's NAME is free; its "
 + 'dot is not).',
 );
 } else if (!stats.ogUrlSkipsProxy) {
 // The break from the OTHER direction: the marker still carries its dot,
 // but the matcher moved under it. Reported here rather than left to the
 // `dottedBypassesProxy` flag, which merely relaxes two limbs below and
 // asserts nothing -- the whole reason this widening could land green.
 findings.push(
 `the OG card URL \`${OG_BUILDER}()\` builds -- \`${probe}\` -- IS matched by proxy.ts's `
 + `matcher, even though its final segment \`${finalSegment}\` still contains a dot. The `
 + 'exclusion the marker relies on moved on the PROXY side: this URL is now locale-rewritten '
 + `to \`/<locale>${probe}\`, a path app/og/ does not serve, because that tree is top-level `
 + 'and not under app/[lang]/. Every `og:image` on the site 404s at once, and nothing fetches '
 + 'these URLs, so no other check sees it. Note this is NOT relaxed by the same widening '
 + 'relaxing the catch-all requirement below: rewriting dotted paths removes the need for the '
 + `locale guard and breaks the OG cards, both at once. Restore an exclusion in `
 + `apps/docs/proxy.ts that covers this URL -- the dot limb (\`.*\\..*\`) is what covered it, `
 + `and excluding the \`/og/\` prefix outright is the narrower alternative. Matcher(s) read: `
 + `${JSON.stringify(read.matchers)}.`,
 );
 }
 }
 }
Expand DownExpand Up@@ -545,14 +585,54 @@ function selfTest() {
 assert(run.stats.segments === 2 && run.stats.guarded === 1, `both segments must be counted -- got ${summarise(run.stats)}`);

 // 6. The condition is LIVE, not decorative: a matcher that DOES cover dotted
 // paths makes the guard unnecessary, and the missing guard goes green.
 // paths makes the locale guard unnecessary, and the missing guard is NOT
 // demanded. That relaxation is kept -- it is correct on its own terms.
 // What is no longer allowed is for it to be the WHOLE story: the same
 // widening takes every `og:image` to 404, so the OG limb reports it here
 // and the run as a whole is red. Before that limb existed this fixture
 // was silent, which is the hole this case now pins from both sides.
 paths = writeFixture(dir, {
 proxy: `export const config = { matcher: ['/((?!api|_next/static).*)'] };\n`,
 layout: FIXTURE_LAYOUT.replace(' if (!isSupportedLanguage(lang)) notFound();\n', ''),
 });
 run = checkApp(paths);
 assert(run.findings.length === 0, `a proxy that rewrites dotted paths must not demand the guard -- got ${JSON.stringify(run.findings)}`);
 assert(run.stats.dottedBypassesProxy === false, 'the widened matcher must be read as covering dotted paths');
 assert(
 !run.findings.some((f) => /never calls|is a top-level catch-all|does not read/.test(f)),
 `a proxy that rewrites dotted paths must still not demand the locale guard -- got ${JSON.stringify(run.findings)}`,
 );
 assert(
 run.findings.length === 1 && /IS matched by proxy\.ts's matcher/.test(run.findings[0]),
 `widening the matcher must be reported by the OG limb, not left green -- got ${JSON.stringify(run.findings)}`,
 );

 // 6b. RED, THE ABLATION FROM THE PROXY SIDE. Nothing but the matcher moves:
 // the guard is present, the marker still ends in `image.png`, every
 // other limb is satisfied and the two conditional limbs have relaxed
 // themselves. The surface is broken anyway, and this is the reading that
 // says so -- taken from the built URL, not from either side alone.
 paths = writeFixture(dir, { proxy: `export const config = { matcher: ['/((?!api|_next/static).*)'] };\n` });
 run = checkApp(paths);
 assert(run.stats.ogFinalSegmentDotted === true, 'the marker must be untouched in the proxy-side ablation');
 assert(run.stats.ogUrlSkipsProxy === false, 'the widened matcher must be read as now covering the OG card URL');
 assert(
 run.findings.length === 1 && /IS matched by proxy\.ts's matcher/.test(run.findings[0]),
 `a matcher that swallowed the OG card URL must be reported once -- got ${JSON.stringify(run.findings)}`,
 );

 // 6c. GREEN control: the limb fires on the BREAK, not on the flag. This
 // matcher drops the dot exclusion -- so the catch-all requirement
 // relaxes exactly as in 6 -- but still excludes the `/og/` prefix, so
 // the cards are still served and there is nothing to report. A limb
 // wired to `dottedBypassesProxy` instead of to the URL would cry here.
 paths = writeFixture(dir, {
 proxy: `export const config = { matcher: ['/((?!api|_next/static|og/).*)'] };\n`,
 layout: FIXTURE_LAYOUT.replace(' if (!isSupportedLanguage(lang)) notFound();\n', ''),
 });
 run = checkApp(paths);
 assert(run.stats.dottedBypassesProxy === false, 'the og-excluding matcher must still be read as covering dotted paths');
 assert(run.stats.ogUrlSkipsProxy === true, 'an excluded `/og/` prefix must be read as still escaping the matcher');
 assert(run.findings.length === 0, `a widening that still excludes /og/ must stay green -- got ${JSON.stringify(run.findings)}`);

 // 7. RED: a matcher that stops rewriting the dotless probe is reported, not
 // silently read as "everything bypasses".
Expand DownExpand Up@@ -625,8 +705,10 @@ function selfTest() {
 `✓ check-docs-locale-catch-all --self-test: ${checked} assertions over a temp fixture (real checkApp path); `
 + 'every limb -- deleted guard, guard behind the return, hollowed predicate, a new unguarded segment, '
 + 'an uncompilable matcher, an OG marker stripped of its dot, an OG marker dropped, an OG url that '
 + 'stopped ending in its segments, a missing builder -- observed FAILING, the proxy condition observed '
 + "flipping the catch-all requirement off, and the OG marker's NAME observed free while its dot is not.",
 + 'stopped ending in its segments, a missing builder, and a matcher widened until it swallows the OG '
 + 'card URL with the marker untouched -- observed FAILING, the proxy condition observed flipping the '
 + "catch-all requirement off WITHOUT taking the run green, the OG marker's NAME observed free while "
 + 'its dot is not, and a widening that still excludes /og/ observed staying green.',
 );
}

Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Assert the OG card URL escapes proxy.ts's matcher, instead of only reporting it#13932

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-project-manager
merged 1 commit into

from

Aug 31, 2026
 Merged


Assert the OG card URL escapes proxy.ts's matcher, instead of only reporting it
#13932
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


102 changes: 92 additions & 10 deletions
scripts/check-docs-locale-catch-all.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -92,10 +92,28 @@
// no type. Silent by construction, which is the same reason the catch-all guard
// above needed a gate rather than a comment.
//
// This limb asserts the half that was asserted nowhere: the URL `getPageImage()`
// builds ends in a final segment containing a dot. It deliberately does NOT
// re-assert that the matcher excludes dotted paths -- that condition is read
// once, above, and both halves are reported in the summary line.
// This limb asserts the invariant on the URL itself, from BOTH ends, because
// the two ends are one surface and either one moving breaks it:
//
// 1. the URL `getPageImage()` builds ends in a final segment containing a
// dot -- the marker side; and
// 2. that URL, compiled against the matcher `proxy.ts` carries TODAY, is not
// matched by it -- the proxy side.
//
// (2) is the direct reading, and it is what makes the conditional catch-all
// requirement below safe to keep. That requirement relaxes when dotted paths
// stop bypassing the proxy, which is correct on its own terms -- but the same
// widening 404s every `og:image`, so a gate that only read the flag could go
// ENTIRELY green on the change that breaks the whole surface: catch-all limb
// relaxed, i18n limb relaxed, and this limb still seeing a dotted marker. A
// reading that licenses a relaxation and is asserted nowhere is not a check; it
// is a statistic with a veto. So the flag keeps its licensing role and this
// limb holds the surface, measured on the built URL rather than on either side.
//
// The two are not redundant: a matcher that widened its dot exclusion but still
// excludes the `/og/` prefix relaxes the catch-all requirement AND leaves the
// cards served, and this limb correctly stays green there. It fires on the
// break, not on the flag.
//
// The assertion is made on the URL the function RETURNS, not on the array
// literal alone. The marker is the URL's final segment only while the returned
Expand DownExpand Up@@ -347,8 +365,12 @@ export function checkApp({ appDir, proxyPath, i18nPath, sourcePath }) {
 // Unconditional, unlike the catch-all guard below -- a matcher that stopped
 // excluding dotted paths would not relax this requirement, it would break the
 // surface outright, so there is no condition under which a dotless marker is
 // the right answer. The matcher half is read once above and reported, never
 // re-asserted here.
 // the right answer. Asserted from BOTH ends on the built URL: the marker must
 // still carry a dot, AND the URL must still escape the matcher `proxy.ts`
 // carries today. The second is the one the `dottedBypassesProxy` flag alone
 // could never make -- the flag LICENSES relaxations below, so leaving its
 // consequence for this surface unasserted is what let a widened matcher take
 // every limb green at once.
 if (!existsSync(sourcePath)) {
 findings.push(`missing ${sourcePath}`);
 } else {
Expand All@@ -371,6 +393,24 @@ export function checkApp({ appDir, proxyPath, i18nPath, sourcePath }) {
 + "final segment containing a dot in apps/docs/lib/source.ts (the marker's NAME is free; its "
 + 'dot is not).',
 );
 } else if (!stats.ogUrlSkipsProxy) {
 // The break from the OTHER direction: the marker still carries its dot,
 // but the matcher moved under it. Reported here rather than left to the
 // `dottedBypassesProxy` flag, which merely relaxes two limbs below and
 // asserts nothing -- the whole reason this widening could land green.
 findings.push(
 `the OG card URL \`${OG_BUILDER}()\` builds -- \`${probe}\` -- IS matched by proxy.ts's `
 + `matcher, even though its final segment \`${finalSegment}\` still contains a dot. The `
 + 'exclusion the marker relies on moved on the PROXY side: this URL is now locale-rewritten '
 + `to \`/<locale>${probe}\`, a path app/og/ does not serve, because that tree is top-level `
 + 'and not under app/[lang]/. Every `og:image` on the site 404s at once, and nothing fetches '
 + 'these URLs, so no other check sees it. Note this is NOT relaxed by the same widening '
 + 'relaxing the catch-all requirement below: rewriting dotted paths removes the need for the '
 + `locale guard and breaks the OG cards, both at once. Restore an exclusion in `
 + `apps/docs/proxy.ts that covers this URL -- the dot limb (\`.*\\..*\`) is what covered it, `
 + `and excluding the \`/og/\` prefix outright is the narrower alternative. Matcher(s) read: `
 + `${JSON.stringify(read.matchers)}.`,
 );
 }
 }
 }
Expand DownExpand Up@@ -545,14 +585,54 @@ function selfTest() {
 assert(run.stats.segments === 2 && run.stats.guarded === 1, `both segments must be counted -- got ${summarise(run.stats)}`);

 // 6. The condition is LIVE, not decorative: a matcher that DOES cover dotted
 // paths makes the guard unnecessary, and the missing guard goes green.
 // paths makes the locale guard unnecessary, and the missing guard is NOT
 // demanded. That relaxation is kept -- it is correct on its own terms.
 // What is no longer allowed is for it to be the WHOLE story: the same
 // widening takes every `og:image` to 404, so the OG limb reports it here
 // and the run as a whole is red. Before that limb existed this fixture
 // was silent, which is the hole this case now pins from both sides.
 paths = writeFixture(dir, {
 proxy: `export const config = { matcher: ['/((?!api|_next/static).*)'] };\n`,
 layout: FIXTURE_LAYOUT.replace(' if (!isSupportedLanguage(lang)) notFound();\n', ''),
 });
 run = checkApp(paths);
 assert(run.findings.length === 0, `a proxy that rewrites dotted paths must not demand the guard -- got ${JSON.stringify(run.findings)}`);
 assert(run.stats.dottedBypassesProxy === false, 'the widened matcher must be read as covering dotted paths');
 assert(
 !run.findings.some((f) => /never calls|is a top-level catch-all|does not read/.test(f)),
 `a proxy that rewrites dotted paths must still not demand the locale guard -- got ${JSON.stringify(run.findings)}`,
 );
 assert(
 run.findings.length === 1 && /IS matched by proxy\.ts's matcher/.test(run.findings[0]),
 `widening the matcher must be reported by the OG limb, not left green -- got ${JSON.stringify(run.findings)}`,
 );

 // 6b. RED, THE ABLATION FROM THE PROXY SIDE. Nothing but the matcher moves:
 // the guard is present, the marker still ends in `image.png`, every
 // other limb is satisfied and the two conditional limbs have relaxed
 // themselves. The surface is broken anyway, and this is the reading that
 // says so -- taken from the built URL, not from either side alone.
 paths = writeFixture(dir, { proxy: `export const config = { matcher: ['/((?!api|_next/static).*)'] };\n` });
 run = checkApp(paths);
 assert(run.stats.ogFinalSegmentDotted === true, 'the marker must be untouched in the proxy-side ablation');
 assert(run.stats.ogUrlSkipsProxy === false, 'the widened matcher must be read as now covering the OG card URL');
 assert(
 run.findings.length === 1 && /IS matched by proxy\.ts's matcher/.test(run.findings[0]),
 `a matcher that swallowed the OG card URL must be reported once -- got ${JSON.stringify(run.findings)}`,
 );

 // 6c. GREEN control: the limb fires on the BREAK, not on the flag. This
 // matcher drops the dot exclusion -- so the catch-all requirement
 // relaxes exactly as in 6 -- but still excludes the `/og/` prefix, so
 // the cards are still served and there is nothing to report. A limb
 // wired to `dottedBypassesProxy` instead of to the URL would cry here.
 paths = writeFixture(dir, {
 proxy: `export const config = { matcher: ['/((?!api|_next/static|og/).*)'] };\n`,
 layout: FIXTURE_LAYOUT.replace(' if (!isSupportedLanguage(lang)) notFound();\n', ''),
 });
 run = checkApp(paths);
 assert(run.stats.dottedBypassesProxy === false, 'the og-excluding matcher must still be read as covering dotted paths');
 assert(run.stats.ogUrlSkipsProxy === true, 'an excluded `/og/` prefix must be read as still escaping the matcher');
 assert(run.findings.length === 0, `a widening that still excludes /og/ must stay green -- got ${JSON.stringify(run.findings)}`);

 // 7. RED: a matcher that stops rewriting the dotless probe is reported, not
 // silently read as "everything bypasses".
Expand DownExpand Up@@ -625,8 +705,10 @@ function selfTest() {
 `✓ check-docs-locale-catch-all --self-test: ${checked} assertions over a temp fixture (real checkApp path); `
 + 'every limb -- deleted guard, guard behind the return, hollowed predicate, a new unguarded segment, '
 + 'an uncompilable matcher, an OG marker stripped of its dot, an OG marker dropped, an OG url that '
 + 'stopped ending in its segments, a missing builder -- observed FAILING, the proxy condition observed '
 + "flipping the catch-all requirement off, and the OG marker's NAME observed free while its dot is not.",
 + 'stopped ending in its segments, a missing builder, and a matcher widened until it swallows the OG '
 + 'card URL with the marker untouched -- observed FAILING, the proxy condition observed flipping the '
 + "catch-all requirement off WITHOUT taking the run green, the OG marker's NAME observed free while "
 + 'its dot is not, and a widening that still excludes /og/ observed staying green.',
 );
}

Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
Assert the OG card URL escapes proxy.ts's matcher, instead of only reporting it#13932

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-project-manager
merged 1 commit into

from

Aug 31, 2026
 Merged


Assert the OG card URL escapes proxy.ts's matcher, instead of only reporting it
#13932
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


102 changes: 92 additions & 10 deletions
scripts/check-docs-locale-catch-all.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -92,10 +92,28 @@
// no type. Silent by construction, which is the same reason the catch-all guard
// above needed a gate rather than a comment.
//
// This limb asserts the half that was asserted nowhere: the URL `getPageImage()`
// builds ends in a final segment containing a dot. It deliberately does NOT
// re-assert that the matcher excludes dotted paths -- that condition is read
// once, above, and both halves are reported in the summary line.
// This limb asserts the invariant on the URL itself, from BOTH ends, because
// the two ends are one surface and either one moving breaks it:
//
// 1. the URL `getPageImage()` builds ends in a final segment containing a
// dot -- the marker side; and
// 2. that URL, compiled against the matcher `proxy.ts` carries TODAY, is not
// matched by it -- the proxy side.
//
// (2) is the direct reading, and it is what makes the conditional catch-all
// requirement below safe to keep. That requirement relaxes when dotted paths
// stop bypassing the proxy, which is correct on its own terms -- but the same
// widening 404s every `og:image`, so a gate that only read the flag could go
// ENTIRELY green on the change that breaks the whole surface: catch-all limb
// relaxed, i18n limb relaxed, and this limb still seeing a dotted marker. A
// reading that licenses a relaxation and is asserted nowhere is not a check; it
// is a statistic with a veto. So the flag keeps its licensing role and this
// limb holds the surface, measured on the built URL rather than on either side.
//
// The two are not redundant: a matcher that widened its dot exclusion but still
// excludes the `/og/` prefix relaxes the catch-all requirement AND leaves the
// cards served, and this limb correctly stays green there. It fires on the
// break, not on the flag.
//
// The assertion is made on the URL the function RETURNS, not on the array
// literal alone. The marker is the URL's final segment only while the returned
Expand DownExpand Up@@ -347,8 +365,12 @@ export function checkApp({ appDir, proxyPath, i18nPath, sourcePath }) {
 // Unconditional, unlike the catch-all guard below -- a matcher that stopped
 // excluding dotted paths would not relax this requirement, it would break the
 // surface outright, so there is no condition under which a dotless marker is
 // the right answer. The matcher half is read once above and reported, never
 // re-asserted here.
 // the right answer. Asserted from BOTH ends on the built URL: the marker must
 // still carry a dot, AND the URL must still escape the matcher `proxy.ts`
 // carries today. The second is the one the `dottedBypassesProxy` flag alone
 // could never make -- the flag LICENSES relaxations below, so leaving its
 // consequence for this surface unasserted is what let a widened matcher take
 // every limb green at once.
 if (!existsSync(sourcePath)) {
 findings.push(`missing ${sourcePath}`);
 } else {
Expand All@@ -371,6 +393,24 @@ export function checkApp({ appDir, proxyPath, i18nPath, sourcePath }) {
 + "final segment containing a dot in apps/docs/lib/source.ts (the marker's NAME is free; its "
 + 'dot is not).',
 );
 } else if (!stats.ogUrlSkipsProxy) {
 // The break from the OTHER direction: the marker still carries its dot,
 // but the matcher moved under it. Reported here rather than left to the
 // `dottedBypassesProxy` flag, which merely relaxes two limbs below and
 // asserts nothing -- the whole reason this widening could land green.
 findings.push(
 `the OG card URL \`${OG_BUILDER}()\` builds -- \`${probe}\` -- IS matched by proxy.ts's `
 + `matcher, even though its final segment \`${finalSegment}\` still contains a dot. The `
 + 'exclusion the marker relies on moved on the PROXY side: this URL is now locale-rewritten '
 + `to \`/<locale>${probe}\`, a path app/og/ does not serve, because that tree is top-level `
 + 'and not under app/[lang]/. Every `og:image` on the site 404s at once, and nothing fetches '
 + 'these URLs, so no other check sees it. Note this is NOT relaxed by the same widening '
 + 'relaxing the catch-all requirement below: rewriting dotted paths removes the need for the '
 + `locale guard and breaks the OG cards, both at once. Restore an exclusion in `
 + `apps/docs/proxy.ts that covers this URL -- the dot limb (\`.*\\..*\`) is what covered it, `
 + `and excluding the \`/og/\` prefix outright is the narrower alternative. Matcher(s) read: `
 + `${JSON.stringify(read.matchers)}.`,
 );
 }
 }
 }
Expand DownExpand Up@@ -545,14 +585,54 @@ function selfTest() {
 assert(run.stats.segments === 2 && run.stats.guarded === 1, `both segments must be counted -- got ${summarise(run.stats)}`);

 // 6. The condition is LIVE, not decorative: a matcher that DOES cover dotted
 // paths makes the guard unnecessary, and the missing guard goes green.
 // paths makes the locale guard unnecessary, and the missing guard is NOT
 // demanded. That relaxation is kept -- it is correct on its own terms.
 // What is no longer allowed is for it to be the WHOLE story: the same
 // widening takes every `og:image` to 404, so the OG limb reports it here
 // and the run as a whole is red. Before that limb existed this fixture
 // was silent, which is the hole this case now pins from both sides.
 paths = writeFixture(dir, {
 proxy: `export const config = { matcher: ['/((?!api|_next/static).*)'] };\n`,
 layout: FIXTURE_LAYOUT.replace(' if (!isSupportedLanguage(lang)) notFound();\n', ''),
 });
 run = checkApp(paths);
 assert(run.findings.length === 0, `a proxy that rewrites dotted paths must not demand the guard -- got ${JSON.stringify(run.findings)}`);
 assert(run.stats.dottedBypassesProxy === false, 'the widened matcher must be read as covering dotted paths');
 assert(
 !run.findings.some((f) => /never calls|is a top-level catch-all|does not read/.test(f)),
 `a proxy that rewrites dotted paths must still not demand the locale guard -- got ${JSON.stringify(run.findings)}`,
 );
 assert(
 run.findings.length === 1 && /IS matched by proxy\.ts's matcher/.test(run.findings[0]),
 `widening the matcher must be reported by the OG limb, not left green -- got ${JSON.stringify(run.findings)}`,
 );

 // 6b. RED, THE ABLATION FROM THE PROXY SIDE. Nothing but the matcher moves:
 // the guard is present, the marker still ends in `image.png`, every
 // other limb is satisfied and the two conditional limbs have relaxed
 // themselves. The surface is broken anyway, and this is the reading that
 // says so -- taken from the built URL, not from either side alone.
 paths = writeFixture(dir, { proxy: `export const config = { matcher: ['/((?!api|_next/static).*)'] };\n` });
 run = checkApp(paths);
 assert(run.stats.ogFinalSegmentDotted === true, 'the marker must be untouched in the proxy-side ablation');
 assert(run.stats.ogUrlSkipsProxy === false, 'the widened matcher must be read as now covering the OG card URL');
 assert(
 run.findings.length === 1 && /IS matched by proxy\.ts's matcher/.test(run.findings[0]),
 `a matcher that swallowed the OG card URL must be reported once -- got ${JSON.stringify(run.findings)}`,
 );

 // 6c. GREEN control: the limb fires on the BREAK, not on the flag. This
 // matcher drops the dot exclusion -- so the catch-all requirement
 // relaxes exactly as in 6 -- but still excludes the `/og/` prefix, so
 // the cards are still served and there is nothing to report. A limb
 // wired to `dottedBypassesProxy` instead of to the URL would cry here.
 paths = writeFixture(dir, {
 proxy: `export const config = { matcher: ['/((?!api|_next/static|og/).*)'] };\n`,
 layout: FIXTURE_LAYOUT.replace(' if (!isSupportedLanguage(lang)) notFound();\n', ''),
 });
 run = checkApp(paths);
 assert(run.stats.dottedBypassesProxy === false, 'the og-excluding matcher must still be read as covering dotted paths');
 assert(run.stats.ogUrlSkipsProxy === true, 'an excluded `/og/` prefix must be read as still escaping the matcher');
 assert(run.findings.length === 0, `a widening that still excludes /og/ must stay green -- got ${JSON.stringify(run.findings)}`);

 // 7. RED: a matcher that stops rewriting the dotless probe is reported, not
 // silently read as "everything bypasses".
Expand DownExpand Up@@ -625,8 +705,10 @@ function selfTest() {
 `✓ check-docs-locale-catch-all --self-test: ${checked} assertions over a temp fixture (real checkApp path); `
 + 'every limb -- deleted guard, guard behind the return, hollowed predicate, a new unguarded segment, '
 + 'an uncompilable matcher, an OG marker stripped of its dot, an OG marker dropped, an OG url that '
 + 'stopped ending in its segments, a missing builder -- observed FAILING, the proxy condition observed '
 + "flipping the catch-all requirement off, and the OG marker's NAME observed free while its dot is not.",
 + 'stopped ending in its segments, a missing builder, and a matcher widened until it swallows the OG '
 + 'card URL with the marker untouched -- observed FAILING, the proxy condition observed flipping the '
 + "catch-all requirement off WITHOUT taking the run green, the OG marker's NAME observed free while "
 + 'its dot is not, and a widening that still excludes /og/ observed staying green.',
 );
}

Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Assert the OG card URL escapes proxy.ts's matcher, instead of only reporting it#13932

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-project-manager
merged 1 commit into

from

Aug 31, 2026
 Merged


Assert the OG card URL escapes proxy.ts's matcher, instead of only reporting it
#13932
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


102 changes: 92 additions & 10 deletions
scripts/check-docs-locale-catch-all.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -92,10 +92,28 @@
// no type. Silent by construction, which is the same reason the catch-all guard
// above needed a gate rather than a comment.
//
// This limb asserts the half that was asserted nowhere: the URL `getPageImage()`
// builds ends in a final segment containing a dot. It deliberately does NOT
// re-assert that the matcher excludes dotted paths -- that condition is read
// once, above, and both halves are reported in the summary line.
// This limb asserts the invariant on the URL itself, from BOTH ends, because
// the two ends are one surface and either one moving breaks it:
//
// 1. the URL `getPageImage()` builds ends in a final segment containing a
// dot -- the marker side; and
// 2. that URL, compiled against the matcher `proxy.ts` carries TODAY, is not
// matched by it -- the proxy side.
//
// (2) is the direct reading, and it is what makes the conditional catch-all
// requirement below safe to keep. That requirement relaxes when dotted paths
// stop bypassing the proxy, which is correct on its own terms -- but the same
// widening 404s every `og:image`, so a gate that only read the flag could go
// ENTIRELY green on the change that breaks the whole surface: catch-all limb
// relaxed, i18n limb relaxed, and this limb still seeing a dotted marker. A
// reading that licenses a relaxation and is asserted nowhere is not a check; it
// is a statistic with a veto. So the flag keeps its licensing role and this
// limb holds the surface, measured on the built URL rather than on either side.
//
// The two are not redundant: a matcher that widened its dot exclusion but still
// excludes the `/og/` prefix relaxes the catch-all requirement AND leaves the
// cards served, and this limb correctly stays green there. It fires on the
// break, not on the flag.
//
// The assertion is made on the URL the function RETURNS, not on the array
// literal alone. The marker is the URL's final segment only while the returned
Expand DownExpand Up@@ -347,8 +365,12 @@ export function checkApp({ appDir, proxyPath, i18nPath, sourcePath }) {
 // Unconditional, unlike the catch-all guard below -- a matcher that stopped
 // excluding dotted paths would not relax this requirement, it would break the
 // surface outright, so there is no condition under which a dotless marker is
 // the right answer. The matcher half is read once above and reported, never
 // re-asserted here.
 // the right answer. Asserted from BOTH ends on the built URL: the marker must
 // still carry a dot, AND the URL must still escape the matcher `proxy.ts`
 // carries today. The second is the one the `dottedBypassesProxy` flag alone
 // could never make -- the flag LICENSES relaxations below, so leaving its
 // consequence for this surface unasserted is what let a widened matcher take
 // every limb green at once.
 if (!existsSync(sourcePath)) {
 findings.push(`missing ${sourcePath}`);
 } else {
Expand All@@ -371,6 +393,24 @@ export function checkApp({ appDir, proxyPath, i18nPath, sourcePath }) {
 + "final segment containing a dot in apps/docs/lib/source.ts (the marker's NAME is free; its "
 + 'dot is not).',
 );
 } else if (!stats.ogUrlSkipsProxy) {
 // The break from the OTHER direction: the marker still carries its dot,
 // but the matcher moved under it. Reported here rather than left to the
 // `dottedBypassesProxy` flag, which merely relaxes two limbs below and
 // asserts nothing -- the whole reason this widening could land green.
 findings.push(
 `the OG card URL \`${OG_BUILDER}()\` builds -- \`${probe}\` -- IS matched by proxy.ts's `
 + `matcher, even though its final segment \`${finalSegment}\` still contains a dot. The `
 + 'exclusion the marker relies on moved on the PROXY side: this URL is now locale-rewritten '
 + `to \`/<locale>${probe}\`, a path app/og/ does not serve, because that tree is top-level `
 + 'and not under app/[lang]/. Every `og:image` on the site 404s at once, and nothing fetches '
 + 'these URLs, so no other check sees it. Note this is NOT relaxed by the same widening '
 + 'relaxing the catch-all requirement below: rewriting dotted paths removes the need for the '
 + `locale guard and breaks the OG cards, both at once. Restore an exclusion in `
 + `apps/docs/proxy.ts that covers this URL -- the dot limb (\`.*\\..*\`) is what covered it, `
 + `and excluding the \`/og/\` prefix outright is the narrower alternative. Matcher(s) read: `
 + `${JSON.stringify(read.matchers)}.`,
 );
 }
 }
 }
Expand DownExpand Up@@ -545,14 +585,54 @@ function selfTest() {
 assert(run.stats.segments === 2 && run.stats.guarded === 1, `both segments must be counted -- got ${summarise(run.stats)}`);

 // 6. The condition is LIVE, not decorative: a matcher that DOES cover dotted
 // paths makes the guard unnecessary, and the missing guard goes green.
 // paths makes the locale guard unnecessary, and the missing guard is NOT
 // demanded. That relaxation is kept -- it is correct on its own terms.
 // What is no longer allowed is for it to be the WHOLE story: the same
 // widening takes every `og:image` to 404, so the OG limb reports it here
 // and the run as a whole is red. Before that limb existed this fixture
 // was silent, which is the hole this case now pins from both sides.
 paths = writeFixture(dir, {
 proxy: `export const config = { matcher: ['/((?!api|_next/static).*)'] };\n`,
 layout: FIXTURE_LAYOUT.replace(' if (!isSupportedLanguage(lang)) notFound();\n', ''),
 });
 run = checkApp(paths);
 assert(run.findings.length === 0, `a proxy that rewrites dotted paths must not demand the guard -- got ${JSON.stringify(run.findings)}`);
 assert(run.stats.dottedBypassesProxy === false, 'the widened matcher must be read as covering dotted paths');
 assert(
 !run.findings.some((f) => /never calls|is a top-level catch-all|does not read/.test(f)),
 `a proxy that rewrites dotted paths must still not demand the locale guard -- got ${JSON.stringify(run.findings)}`,
 );
 assert(
 run.findings.length === 1 && /IS matched by proxy\.ts's matcher/.test(run.findings[0]),
 `widening the matcher must be reported by the OG limb, not left green -- got ${JSON.stringify(run.findings)}`,
 );

 // 6b. RED, THE ABLATION FROM THE PROXY SIDE. Nothing but the matcher moves:
 // the guard is present, the marker still ends in `image.png`, every
 // other limb is satisfied and the two conditional limbs have relaxed
 // themselves. The surface is broken anyway, and this is the reading that
 // says so -- taken from the built URL, not from either side alone.
 paths = writeFixture(dir, { proxy: `export const config = { matcher: ['/((?!api|_next/static).*)'] };\n` });
 run = checkApp(paths);
 assert(run.stats.ogFinalSegmentDotted === true, 'the marker must be untouched in the proxy-side ablation');
 assert(run.stats.ogUrlSkipsProxy === false, 'the widened matcher must be read as now covering the OG card URL');
 assert(
 run.findings.length === 1 && /IS matched by proxy\.ts's matcher/.test(run.findings[0]),
 `a matcher that swallowed the OG card URL must be reported once -- got ${JSON.stringify(run.findings)}`,
 );

 // 6c. GREEN control: the limb fires on the BREAK, not on the flag. This
 // matcher drops the dot exclusion -- so the catch-all requirement
 // relaxes exactly as in 6 -- but still excludes the `/og/` prefix, so
 // the cards are still served and there is nothing to report. A limb
 // wired to `dottedBypassesProxy` instead of to the URL would cry here.
 paths = writeFixture(dir, {
 proxy: `export const config = { matcher: ['/((?!api|_next/static|og/).*)'] };\n`,
 layout: FIXTURE_LAYOUT.replace(' if (!isSupportedLanguage(lang)) notFound();\n', ''),
 });
 run = checkApp(paths);
 assert(run.stats.dottedBypassesProxy === false, 'the og-excluding matcher must still be read as covering dotted paths');
 assert(run.stats.ogUrlSkipsProxy === true, 'an excluded `/og/` prefix must be read as still escaping the matcher');
 assert(run.findings.length === 0, `a widening that still excludes /og/ must stay green -- got ${JSON.stringify(run.findings)}`);

 // 7. RED: a matcher that stops rewriting the dotless probe is reported, not
 // silently read as "everything bypasses".
Expand DownExpand Up@@ -625,8 +705,10 @@ function selfTest() {
 `✓ check-docs-locale-catch-all --self-test: ${checked} assertions over a temp fixture (real checkApp path); `
 + 'every limb -- deleted guard, guard behind the return, hollowed predicate, a new unguarded segment, '
 + 'an uncompilable matcher, an OG marker stripped of its dot, an OG marker dropped, an OG url that '
 + 'stopped ending in its segments, a missing builder -- observed FAILING, the proxy condition observed '
 + "flipping the catch-all requirement off, and the OG marker's NAME observed free while its dot is not.",
 + 'stopped ending in its segments, a missing builder, and a matcher widened until it swallows the OG '
 + 'card URL with the marker untouched -- observed FAILING, the proxy condition observed flipping the '
 + "catch-all requirement off WITHOUT taking the run green, the OG marker's NAME observed free while "
 + 'its dot is not, and a widening that still excludes /og/ observed staying green.',
 );
}

Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Assert the OG card URL escapes proxy.ts's matcher, instead of only reporting it#13932

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-project-manager
merged 1 commit into

from

Aug 31, 2026
 Merged


Assert the OG card URL escapes proxy.ts's matcher, instead of only reporting it
#13932
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


102 changes: 92 additions & 10 deletions
scripts/check-docs-locale-catch-all.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -92,10 +92,28 @@
// no type. Silent by construction, which is the same reason the catch-all guard
// above needed a gate rather than a comment.
//
// This limb asserts the half that was asserted nowhere: the URL `getPageImage()`
// builds ends in a final segment containing a dot. It deliberately does NOT
// re-assert that the matcher excludes dotted paths -- that condition is read
// once, above, and both halves are reported in the summary line.
// This limb asserts the invariant on the URL itself, from BOTH ends, because
// the two ends are one surface and either one moving breaks it:
//
// 1. the URL `getPageImage()` builds ends in a final segment containing a
// dot -- the marker side; and
// 2. that URL, compiled against the matcher `proxy.ts` carries TODAY, is not
// matched by it -- the proxy side.
//
// (2) is the direct reading, and it is what makes the conditional catch-all
// requirement below safe to keep. That requirement relaxes when dotted paths
// stop bypassing the proxy, which is correct on its own terms -- but the same
// widening 404s every `og:image`, so a gate that only read the flag could go
// ENTIRELY green on the change that breaks the whole surface: catch-all limb
// relaxed, i18n limb relaxed, and this limb still seeing a dotted marker. A
// reading that licenses a relaxation and is asserted nowhere is not a check; it
// is a statistic with a veto. So the flag keeps its licensing role and this
// limb holds the surface, measured on the built URL rather than on either side.
//
// The two are not redundant: a matcher that widened its dot exclusion but still
// excludes the `/og/` prefix relaxes the catch-all requirement AND leaves the
// cards served, and this limb correctly stays green there. It fires on the
// break, not on the flag.
//
// The assertion is made on the URL the function RETURNS, not on the array
// literal alone. The marker is the URL's final segment only while the returned
Expand DownExpand Up@@ -347,8 +365,12 @@ export function checkApp({ appDir, proxyPath, i18nPath, sourcePath }) {
 // Unconditional, unlike the catch-all guard below -- a matcher that stopped
 // excluding dotted paths would not relax this requirement, it would break the
 // surface outright, so there is no condition under which a dotless marker is
 // the right answer. The matcher half is read once above and reported, never
 // re-asserted here.
 // the right answer. Asserted from BOTH ends on the built URL: the marker must
 // still carry a dot, AND the URL must still escape the matcher `proxy.ts`
 // carries today. The second is the one the `dottedBypassesProxy` flag alone
 // could never make -- the flag LICENSES relaxations below, so leaving its
 // consequence for this surface unasserted is what let a widened matcher take
 // every limb green at once.
 if (!existsSync(sourcePath)) {
 findings.push(`missing ${sourcePath}`);
 } else {
Expand All@@ -371,6 +393,24 @@ export function checkApp({ appDir, proxyPath, i18nPath, sourcePath }) {
 + "final segment containing a dot in apps/docs/lib/source.ts (the marker's NAME is free; its "
 + 'dot is not).',
 );
 } else if (!stats.ogUrlSkipsProxy) {
 // The break from the OTHER direction: the marker still carries its dot,
 // but the matcher moved under it. Reported here rather than left to the
 // `dottedBypassesProxy` flag, which merely relaxes two limbs below and
 // asserts nothing -- the whole reason this widening could land green.
 findings.push(
 `the OG card URL \`${OG_BUILDER}()\` builds -- \`${probe}\` -- IS matched by proxy.ts's `
 + `matcher, even though its final segment \`${finalSegment}\` still contains a dot. The `
 + 'exclusion the marker relies on moved on the PROXY side: this URL is now locale-rewritten '
 + `to \`/<locale>${probe}\`, a path app/og/ does not serve, because that tree is top-level `
 + 'and not under app/[lang]/. Every `og:image` on the site 404s at once, and nothing fetches '
 + 'these URLs, so no other check sees it. Note this is NOT relaxed by the same widening '
 + 'relaxing the catch-all requirement below: rewriting dotted paths removes the need for the '
 + `locale guard and breaks the OG cards, both at once. Restore an exclusion in `
 + `apps/docs/proxy.ts that covers this URL -- the dot limb (\`.*\\..*\`) is what covered it, `
 + `and excluding the \`/og/\` prefix outright is the narrower alternative. Matcher(s) read: `
 + `${JSON.stringify(read.matchers)}.`,
 );
 }
 }
 }
Expand DownExpand Up@@ -545,14 +585,54 @@ function selfTest() {
 assert(run.stats.segments === 2 && run.stats.guarded === 1, `both segments must be counted -- got ${summarise(run.stats)}`);

 // 6. The condition is LIVE, not decorative: a matcher that DOES cover dotted
 // paths makes the guard unnecessary, and the missing guard goes green.
 // paths makes the locale guard unnecessary, and the missing guard is NOT
 // demanded. That relaxation is kept -- it is correct on its own terms.
 // What is no longer allowed is for it to be the WHOLE story: the same
 // widening takes every `og:image` to 404, so the OG limb reports it here
 // and the run as a whole is red. Before that limb existed this fixture
 // was silent, which is the hole this case now pins from both sides.
 paths = writeFixture(dir, {
 proxy: `export const config = { matcher: ['/((?!api|_next/static).*)'] };\n`,
 layout: FIXTURE_LAYOUT.replace(' if (!isSupportedLanguage(lang)) notFound();\n', ''),
 });
 run = checkApp(paths);
 assert(run.findings.length === 0, `a proxy that rewrites dotted paths must not demand the guard -- got ${JSON.stringify(run.findings)}`);
 assert(run.stats.dottedBypassesProxy === false, 'the widened matcher must be read as covering dotted paths');
 assert(
 !run.findings.some((f) => /never calls|is a top-level catch-all|does not read/.test(f)),
 `a proxy that rewrites dotted paths must still not demand the locale guard -- got ${JSON.stringify(run.findings)}`,
 );
 assert(
 run.findings.length === 1 && /IS matched by proxy\.ts's matcher/.test(run.findings[0]),
 `widening the matcher must be reported by the OG limb, not left green -- got ${JSON.stringify(run.findings)}`,
 );

 // 6b. RED, THE ABLATION FROM THE PROXY SIDE. Nothing but the matcher moves:
 // the guard is present, the marker still ends in `image.png`, every
 // other limb is satisfied and the two conditional limbs have relaxed
 // themselves. The surface is broken anyway, and this is the reading that
 // says so -- taken from the built URL, not from either side alone.
 paths = writeFixture(dir, { proxy: `export const config = { matcher: ['/((?!api|_next/static).*)'] };\n` });
 run = checkApp(paths);
 assert(run.stats.ogFinalSegmentDotted === true, 'the marker must be untouched in the proxy-side ablation');
 assert(run.stats.ogUrlSkipsProxy === false, 'the widened matcher must be read as now covering the OG card URL');
 assert(
 run.findings.length === 1 && /IS matched by proxy\.ts's matcher/.test(run.findings[0]),
 `a matcher that swallowed the OG card URL must be reported once -- got ${JSON.stringify(run.findings)}`,
 );

 // 6c. GREEN control: the limb fires on the BREAK, not on the flag. This
 // matcher drops the dot exclusion -- so the catch-all requirement
 // relaxes exactly as in 6 -- but still excludes the `/og/` prefix, so
 // the cards are still served and there is nothing to report. A limb
 // wired to `dottedBypassesProxy` instead of to the URL would cry here.
 paths = writeFixture(dir, {
 proxy: `export const config = { matcher: ['/((?!api|_next/static|og/).*)'] };\n`,
 layout: FIXTURE_LAYOUT.replace(' if (!isSupportedLanguage(lang)) notFound();\n', ''),
 });
 run = checkApp(paths);
 assert(run.stats.dottedBypassesProxy === false, 'the og-excluding matcher must still be read as covering dotted paths');
 assert(run.stats.ogUrlSkipsProxy === true, 'an excluded `/og/` prefix must be read as still escaping the matcher');
 assert(run.findings.length === 0, `a widening that still excludes /og/ must stay green -- got ${JSON.stringify(run.findings)}`);

 // 7. RED: a matcher that stops rewriting the dotless probe is reported, not
 // silently read as "everything bypasses".
Expand DownExpand Up@@ -625,8 +705,10 @@ function selfTest() {
 `✓ check-docs-locale-catch-all --self-test: ${checked} assertions over a temp fixture (real checkApp path); `
 + 'every limb -- deleted guard, guard behind the return, hollowed predicate, a new unguarded segment, '
 + 'an uncompilable matcher, an OG marker stripped of its dot, an OG marker dropped, an OG url that '
 + 'stopped ending in its segments, a missing builder -- observed FAILING, the proxy condition observed '
 + "flipping the catch-all requirement off, and the OG marker's NAME observed free while its dot is not.",
 + 'stopped ending in its segments, a missing builder, and a matcher widened until it swallows the OG '
 + 'card URL with the marker untouched -- observed FAILING, the proxy condition observed flipping the '
 + "catch-all requirement off WITHOUT taking the run green, the OG marker's NAME observed free while "
 + 'its dot is not, and a widening that still excludes /og/ observed staying green.',
 );
}

Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
Assert the OG card URL escapes proxy.ts's matcher, instead of only reporting it#13932

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-project-manager
merged 1 commit into

from

Aug 31, 2026
 Merged


Assert the OG card URL escapes proxy.ts's matcher, instead of only reporting it
#13932
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


102 changes: 92 additions & 10 deletions
scripts/check-docs-locale-catch-all.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -92,10 +92,28 @@
// no type. Silent by construction, which is the same reason the catch-all guard
// above needed a gate rather than a comment.
//
// This limb asserts the half that was asserted nowhere: the URL `getPageImage()`
// builds ends in a final segment containing a dot. It deliberately does NOT
// re-assert that the matcher excludes dotted paths -- that condition is read
// once, above, and both halves are reported in the summary line.
// This limb asserts the invariant on the URL itself, from BOTH ends, because
// the two ends are one surface and either one moving breaks it:
//
// 1. the URL `getPageImage()` builds ends in a final segment containing a
// dot -- the marker side; and
// 2. that URL, compiled against the matcher `proxy.ts` carries TODAY, is not
// matched by it -- the proxy side.
//
// (2) is the direct reading, and it is what makes the conditional catch-all
// requirement below safe to keep. That requirement relaxes when dotted paths
// stop bypassing the proxy, which is correct on its own terms -- but the same
// widening 404s every `og:image`, so a gate that only read the flag could go
// ENTIRELY green on the change that breaks the whole surface: catch-all limb
// relaxed, i18n limb relaxed, and this limb still seeing a dotted marker. A
// reading that licenses a relaxation and is asserted nowhere is not a check; it
// is a statistic with a veto. So the flag keeps its licensing role and this
// limb holds the surface, measured on the built URL rather than on either side.
//
// The two are not redundant: a matcher that widened its dot exclusion but still
// excludes the `/og/` prefix relaxes the catch-all requirement AND leaves the
// cards served, and this limb correctly stays green there. It fires on the
// break, not on the flag.
//
// The assertion is made on the URL the function RETURNS, not on the array
// literal alone. The marker is the URL's final segment only while the returned
Expand DownExpand Up@@ -347,8 +365,12 @@ export function checkApp({ appDir, proxyPath, i18nPath, sourcePath }) {
 // Unconditional, unlike the catch-all guard below -- a matcher that stopped
 // excluding dotted paths would not relax this requirement, it would break the
 // surface outright, so there is no condition under which a dotless marker is
 // the right answer. The matcher half is read once above and reported, never
 // re-asserted here.
 // the right answer. Asserted from BOTH ends on the built URL: the marker must
 // still carry a dot, AND the URL must still escape the matcher `proxy.ts`
 // carries today. The second is the one the `dottedBypassesProxy` flag alone
 // could never make -- the flag LICENSES relaxations below, so leaving its
 // consequence for this surface unasserted is what let a widened matcher take
 // every limb green at once.
 if (!existsSync(sourcePath)) {
 findings.push(`missing ${sourcePath}`);
 } else {
Expand All@@ -371,6 +393,24 @@ export function checkApp({ appDir, proxyPath, i18nPath, sourcePath }) {
 + "final segment containing a dot in apps/docs/lib/source.ts (the marker's NAME is free; its "
 + 'dot is not).',
 );
 } else if (!stats.ogUrlSkipsProxy) {
 // The break from the OTHER direction: the marker still carries its dot,
 // but the matcher moved under it. Reported here rather than left to the
 // `dottedBypassesProxy` flag, which merely relaxes two limbs below and
 // asserts nothing -- the whole reason this widening could land green.
 findings.push(
 `the OG card URL \`${OG_BUILDER}()\` builds -- \`${probe}\` -- IS matched by proxy.ts's `
 + `matcher, even though its final segment \`${finalSegment}\` still contains a dot. The `
 + 'exclusion the marker relies on moved on the PROXY side: this URL is now locale-rewritten '
 + `to \`/<locale>${probe}\`, a path app/og/ does not serve, because that tree is top-level `
 + 'and not under app/[lang]/. Every `og:image` on the site 404s at once, and nothing fetches '
 + 'these URLs, so no other check sees it. Note this is NOT relaxed by the same widening '
 + 'relaxing the catch-all requirement below: rewriting dotted paths removes the need for the '
 + `locale guard and breaks the OG cards, both at once. Restore an exclusion in `
 + `apps/docs/proxy.ts that covers this URL -- the dot limb (\`.*\\..*\`) is what covered it, `
 + `and excluding the \`/og/\` prefix outright is the narrower alternative. Matcher(s) read: `
 + `${JSON.stringify(read.matchers)}.`,
 );
 }
 }
 }
Expand DownExpand Up@@ -545,14 +585,54 @@ function selfTest() {
 assert(run.stats.segments === 2 && run.stats.guarded === 1, `both segments must be counted -- got ${summarise(run.stats)}`);

 // 6. The condition is LIVE, not decorative: a matcher that DOES cover dotted
 // paths makes the guard unnecessary, and the missing guard goes green.
 // paths makes the locale guard unnecessary, and the missing guard is NOT
 // demanded. That relaxation is kept -- it is correct on its own terms.
 // What is no longer allowed is for it to be the WHOLE story: the same
 // widening takes every `og:image` to 404, so the OG limb reports it here
 // and the run as a whole is red. Before that limb existed this fixture
 // was silent, which is the hole this case now pins from both sides.
 paths = writeFixture(dir, {
 proxy: `export const config = { matcher: ['/((?!api|_next/static).*)'] };\n`,
 layout: FIXTURE_LAYOUT.replace(' if (!isSupportedLanguage(lang)) notFound();\n', ''),
 });
 run = checkApp(paths);
 assert(run.findings.length === 0, `a proxy that rewrites dotted paths must not demand the guard -- got ${JSON.stringify(run.findings)}`);
 assert(run.stats.dottedBypassesProxy === false, 'the widened matcher must be read as covering dotted paths');
 assert(
 !run.findings.some((f) => /never calls|is a top-level catch-all|does not read/.test(f)),
 `a proxy that rewrites dotted paths must still not demand the locale guard -- got ${JSON.stringify(run.findings)}`,
 );
 assert(
 run.findings.length === 1 && /IS matched by proxy\.ts's matcher/.test(run.findings[0]),
 `widening the matcher must be reported by the OG limb, not left green -- got ${JSON.stringify(run.findings)}`,
 );

 // 6b. RED, THE ABLATION FROM THE PROXY SIDE. Nothing but the matcher moves:
 // the guard is present, the marker still ends in `image.png`, every
 // other limb is satisfied and the two conditional limbs have relaxed
 // themselves. The surface is broken anyway, and this is the reading that
 // says so -- taken from the built URL, not from either side alone.
 paths = writeFixture(dir, { proxy: `export const config = { matcher: ['/((?!api|_next/static).*)'] };\n` });
 run = checkApp(paths);
 assert(run.stats.ogFinalSegmentDotted === true, 'the marker must be untouched in the proxy-side ablation');
 assert(run.stats.ogUrlSkipsProxy === false, 'the widened matcher must be read as now covering the OG card URL');
 assert(
 run.findings.length === 1 && /IS matched by proxy\.ts's matcher/.test(run.findings[0]),
 `a matcher that swallowed the OG card URL must be reported once -- got ${JSON.stringify(run.findings)}`,
 );

 // 6c. GREEN control: the limb fires on the BREAK, not on the flag. This
 // matcher drops the dot exclusion -- so the catch-all requirement
 // relaxes exactly as in 6 -- but still excludes the `/og/` prefix, so
 // the cards are still served and there is nothing to report. A limb
 // wired to `dottedBypassesProxy` instead of to the URL would cry here.
 paths = writeFixture(dir, {
 proxy: `export const config = { matcher: ['/((?!api|_next/static|og/).*)'] };\n`,
 layout: FIXTURE_LAYOUT.replace(' if (!isSupportedLanguage(lang)) notFound();\n', ''),
 });
 run = checkApp(paths);
 assert(run.stats.dottedBypassesProxy === false, 'the og-excluding matcher must still be read as covering dotted paths');
 assert(run.stats.ogUrlSkipsProxy === true, 'an excluded `/og/` prefix must be read as still escaping the matcher');
 assert(run.findings.length === 0, `a widening that still excludes /og/ must stay green -- got ${JSON.stringify(run.findings)}`);

 // 7. RED: a matcher that stops rewriting the dotless probe is reported, not
 // silently read as "everything bypasses".
Expand DownExpand Up@@ -625,8 +705,10 @@ function selfTest() {
 `✓ check-docs-locale-catch-all --self-test: ${checked} assertions over a temp fixture (real checkApp path); `
 + 'every limb -- deleted guard, guard behind the return, hollowed predicate, a new unguarded segment, '
 + 'an uncompilable matcher, an OG marker stripped of its dot, an OG marker dropped, an OG url that '
 + 'stopped ending in its segments, a missing builder -- observed FAILING, the proxy condition observed '
 + "flipping the catch-all requirement off, and the OG marker's NAME observed free while its dot is not.",
 + 'stopped ending in its segments, a missing builder, and a matcher widened until it swallows the OG '
 + 'card URL with the marker untouched -- observed FAILING, the proxy condition observed flipping the '
 + "catch-all requirement off WITHOUT taking the run green, the OG marker's NAME observed free while "
 + 'its dot is not, and a widening that still excludes /og/ observed staying green.',
 );
}

Expand Down
Loading