docs-audit: let a SCREAMING_SNAKE literal mint an anchor, and pin the predicate pair#13782

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

docs-audit: let a SCREAMING_SNAKE literal mint an anchor, and pin the predicate pair #13782

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
101 changes: 96 additions & 5 deletions scripts/docs-audit/affected-docs.mjs
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -1238,6 +1238,64 @@ function noteFrom(map, token, clause) {
set.add(clause);
}

/**
* Is this quoted span identifier-shaped enough to mint a `literal` anchor?
*
* FOUR SHAPES. Three of them say "an identifier starts lowercase" — snake_case,
* camelCase, a dotted client path. A quoted English word (`'ignore'`, `'utf8'`) is not a
* surface anyone documents by that spelling, and those three keep it out.
*
* THE FOURTH IS SCREAMING_SNAKE, AND IT IS HERE TO END A DISAGREEMENT (#13471). While the
* three lowercase-initial shapes were the whole rule, this predicate and `isCodeShaped`
* contradicted each other on every constant name: `isCodeShaped('OS_MODE')` is `true` —
* pinned as `SCREAMING_SNAKE` in the shape cases below since the guard was written — while
* this test declined to mint an anchor from it at all. One predicate in the pair called the
* token an identifier, the other silently called it prose, and nothing reported the split.
* A page that names env vars and essentially nothing else (`deployment/environment-variables.mdx`)
* has no other `literal` route onto an advisory.
*
* The fourth shape is earned by the same argument that earns `PHRASE_ANCHOR_KINDS` its
* exemption — DISTINCTIVE BY CONSTRUCTION, not by inspection. `OS_TENANCY_POSTURE` cannot
* be the English word this guard exists to drop: prose does not shout in underscores. Note
* the shape is MULTI-SEGMENT by construction (the `_` is required), so a bare all-caps word
* is not admitted by it — see the deliberate-disagreement pins in `--self-test`.
*
* MEASURED BOTH WAYS before widening, over the 60 most recent `packages/**` commits, using
* the per-row provenance #12824 published so each added row could be attributed to the
* declaration that minted it rather than counted in a lump:
* - rows 374 -> 383 (+9, +2.4%), and ZERO rows lost;
* - `overbroadAnchors` 8 -> 8: the corpus-share guard caught no new hub term, so the
* widening minted no term broad enough to need catching;
* - only 2 of the 60 runs moved at all. Every new anchor named its declaration:
* `FlowRefusalCode`, `AUTHZ_STORE_UNAVAILABLE_CODE`, `codes`.
* - GROUND TRUTH on `b6d3d76b5`, whose own commit edited three docs pages: the advisory
* went from 0 of those 3 (it listed two `releases/**` pages and nothing else) to 2 of 3
* — `api/client-sdk.mdx` and `automation/flows.mdx`, both minted from `FlowRefusalCode`.
* - the four vendor codes in that window (`ER_DUP_KEYNAME` and friends, from a MySQL
* driver table) minted anchors and matched NO page, so they cost nothing: an anchor
* no doc names is not a row.
*
* BLAST RADIUS, KEPT HONEST. `4d98d9eab` is the commit this was found on, and the widening
* adds ZERO rows there: `environment-variables.mdx` was already listed through the `route`
* anchor `/api/v1/runtime/config`, so all the fourth shape adds is a second `via` clause
* saying `OS_TELEMETRY_CLIENT_ERROR_REPORTING_ENABLED` also pointed at it. The recall win is
* real and it is `b6d3d76b5`-shaped, not `4d98d9eab`-shaped.
*
* DO NOT COLLAPSE THIS INTO `isCodeShaped`. It looks like the same question and it is not,
* because the two run over DIFFERENT POPULATIONS: `isCodeShaped` judges a token already
* known to be a declaration NAME, while this one judges an arbitrary quoted span, which may
* be prose someone quoted. Measured on the same 60 commits, delegating this test to
* `isCodeShaped` gives rows 374 -> 408 (+9.1%, versus +2.4%) and admits `'unchanged.'`,
* `'means.'` and `'version.'` — sentence fragments that reach `isCodeShaped`'s `.` arm.
* Those three are pinned as non-anchors in `--self-test` so the collapse goes red.
*/
function isLiteralAnchorShape(lit) {
return /^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/.test(lit) // snake_case
|| /^[a-z]+(?:[A-Z][A-Za-z0-9]*)+$/.test(lit) // camelCase
|| /^[a-z][a-z0-9]*(?:\.[a-z][A-Za-z0-9]*)+$/.test(lit) // a dotted client path
|| /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/.test(lit); // SCREAMING_SNAKE (#13471)
}

/** Route tails and identifier-shaped string literals appearing on the changed lines. */
function literalAnchorsFromLines(lines, changed) {
const routes = new Set();
Expand DownExpand Up@@ -1266,9 +1324,7 @@ function literalAnchorsFromLines(lines, changed) {
for (const m of line.matchAll(/['"]([A-Za-z][\w.$-]{3,63})['"]/g)) {
const lit = m[1];
if (GENERIC_ANCHOR_NAMES.has(lit.toLowerCase())) continue;
// Identifier-shaped only: snake_case, camelCase or dotted. A quoted English word
// ('ignore', 'utf8') is not a surface anyone documents by that spelling.
if (!/^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/.test(lit) && !/^[a-z]+(?:[A-Z][A-Za-z0-9]*)+$/.test(lit) && !/^[a-z][a-z0-9]*(?:\.[a-z][A-Za-z0-9]*)+$/.test(lit)) continue;
if (!isLiteralAnchorShape(lit)) continue;
literals.add(lit);
const where = enclosingName();
noteFrom(from, lit, where ? `a string literal in ${where}` : 'a string literal on a changed line');
Expand DownExpand Up@@ -4348,15 +4404,50 @@ function selfTest() {
check('PHRASE_ANCHOR_KINDS', 'a rule expression is distinctive by construction', 'rule', true, PHRASE_ANCHOR_KINDS.has('rule'));

// String literals on a changed line: an identifier-shaped one is surface, English is not.
const litLines = [" if (rule === 'controlled_by_parent') return maskFieldValue(v);", " fs.readFileSync(p, 'utf8');", " logger.warn('ignore');"];
const lits = literalAnchorsFromLines(litLines, [1, 2, 3]).literals;
const litLines = [" if (rule === 'controlled_by_parent') return maskFieldValue(v);", " fs.readFileSync(p, 'utf8');", " logger.warn('ignore');",
" const ENV = 'OS_TENANCY_POSTURE';", " if (c === 'FLOW_NO_START_NODE') return refuse(c);",
" // the shape is 'unchanged.' in that arm", " throw new Error('EEXIT');"];
const lits = literalAnchorsFromLines(litLines, [1, 2, 3, 4, 5, 6, 7]).literals;
const literalCases = [
['controlled_by_parent', true, 'a snake_case literal IS an authoring surface'],
['utf8', false, 'an encoding name is not surface'],
['ignore', false, 'an English word is not surface'],
// #13471. The env-var name is the case the whole card was filed on: a page that names
// env vars and essentially nothing else has no other `literal` route onto an advisory.
['OS_TENANCY_POSTURE', true, 'a SCREAMING_SNAKE env-var name IS an authoring surface'],
['FLOW_NO_START_NODE', true, 'and so is a refusal code — the measured recall win'],
// ⛔ The guard rail on the widening, both halves measured on the same 60 commits.
['unchanged.', false, 'a quoted sentence fragment is still not surface'],
['EEXIT', false, 'a bare all-caps word is not SCREAMING_SNAKE — the shape needs a segment break'],
];
for (const [lit, want, label] of literalCases) check('literalAnchorsFromLines', label, lit, want, lits.has(lit));

// ── THE PAIR MUST AGREE ON SCREAMING_SNAKE (#13471) ──
// The defect this closed was not "recall too low", it was TWO PREDICATES CONTRADICTING
// each other with nothing reporting the split: `isCodeShaped` called `OS_MODE` an
// identifier (pinned in `shapeCases` above) while `literalAnchorsFromLines` declined to
// mint any anchor from it. Pin the agreement itself, so neither side can drift back out
// of step silently — a check on one predicate alone could not have caught this.
for (const t of ['OS_CLOUD_URL', 'OS_MODE', 'OS_TENANCY_POSTURE', 'ERROR_CODE_LEDGER', 'FLOW_INPUT_SCHEMA_INVALID']) {
check('isCodeShaped/isLiteralAnchorShape', 'the pair agrees on a SCREAMING_SNAKE token', t,
true, isCodeShaped(t) === isLiteralAnchorShape(t) && isLiteralAnchorShape(t));
}

// ⛔ AND THE DISAGREEMENTS THAT REMAIN ARE DELIBERATE, so the next reader does not
// "finish the job" by collapsing this test into `isCodeShaped`. The two run over
// DIFFERENT POPULATIONS — a declaration NAME versus an arbitrary quoted span that may be
// prose — and delegating measured rows 374 -> 408 (+9.1%, versus +2.4% for the shape
// above) on the same 60 commits. These three fragments are what it admits.
const deliberateSplits = [
['unchanged.', 'a sentence fragment reaches isCodeShaped through its `.` arm'],
['means.', 'ditto — measured, not hypothetical'],
['version.', 'ditto'],
['IHttpRequest', 'a PascalCase name is already reachable through the `symbol` kind'],
];
for (const [t, label] of deliberateSplits) {
check('isCodeShaped/isLiteralAnchorShape', label, t, true, isCodeShaped(t) && !isLiteralAnchorShape(t));
}

// ── `computedOn` (#9519): the record that names WHICH TREE the answer is about ──
// Pinned on the pure shaper, so these stay hermetic; the probing wrapper reads real
// git state by construction. Two properties carry the field's whole value: a merge
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
docs-audit: let a SCREAMING_SNAKE literal mint an anchor, and pin the predicate pair#13782

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


docs-audit: let a SCREAMING_SNAKE literal mint an anchor, and pin the predicate pair
#13782
 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


101 changes: 96 additions & 5 deletions
scripts/docs-audit/affected-docs.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -1238,6 +1238,64 @@ function noteFrom(map, token, clause) {
 set.add(clause);
}

/**
 * Is this quoted span identifier-shaped enough to mint a `literal` anchor?
 *
 * FOUR SHAPES. Three of them say "an identifier starts lowercase" — snake_case,
 * camelCase, a dotted client path. A quoted English word (`'ignore'`, `'utf8'`) is not a
 * surface anyone documents by that spelling, and those three keep it out.
 *
 * THE FOURTH IS SCREAMING_SNAKE, AND IT IS HERE TO END A DISAGREEMENT (#13471). While the
 * three lowercase-initial shapes were the whole rule, this predicate and `isCodeShaped`
 * contradicted each other on every constant name: `isCodeShaped('OS_MODE')` is `true` —
 * pinned as `SCREAMING_SNAKE` in the shape cases below since the guard was written — while
 * this test declined to mint an anchor from it at all. One predicate in the pair called the
 * token an identifier, the other silently called it prose, and nothing reported the split.
 * A page that names env vars and essentially nothing else (`deployment/environment-variables.mdx`)
 * has no other `literal` route onto an advisory.
 *
 * The fourth shape is earned by the same argument that earns `PHRASE_ANCHOR_KINDS` its
 * exemption — DISTINCTIVE BY CONSTRUCTION, not by inspection. `OS_TENANCY_POSTURE` cannot
 * be the English word this guard exists to drop: prose does not shout in underscores. Note
 * the shape is MULTI-SEGMENT by construction (the `_` is required), so a bare all-caps word
 * is not admitted by it — see the deliberate-disagreement pins in `--self-test`.
 *
 * MEASURED BOTH WAYS before widening, over the 60 most recent `packages/**` commits, using
 * the per-row provenance #12824 published so each added row could be attributed to the
 * declaration that minted it rather than counted in a lump:
 * - rows 374 -> 383 (+9, +2.4%), and ZERO rows lost;
 * - `overbroadAnchors` 8 -> 8: the corpus-share guard caught no new hub term, so the
 * widening minted no term broad enough to need catching;
 * - only 2 of the 60 runs moved at all. Every new anchor named its declaration:
 * `FlowRefusalCode`, `AUTHZ_STORE_UNAVAILABLE_CODE`, `codes`.
 * - GROUND TRUTH on `b6d3d76b5`, whose own commit edited three docs pages: the advisory
 * went from 0 of those 3 (it listed two `releases/**` pages and nothing else) to 2 of 3
 * — `api/client-sdk.mdx` and `automation/flows.mdx`, both minted from `FlowRefusalCode`.
 * - the four vendor codes in that window (`ER_DUP_KEYNAME` and friends, from a MySQL
 * driver table) minted anchors and matched NO page, so they cost nothing: an anchor
 * no doc names is not a row.
 *
 * BLAST RADIUS, KEPT HONEST. `4d98d9eab` is the commit this was found on, and the widening
 * adds ZERO rows there: `environment-variables.mdx` was already listed through the `route`
 * anchor `/api/v1/runtime/config`, so all the fourth shape adds is a second `via` clause
 * saying `OS_TELEMETRY_CLIENT_ERROR_REPORTING_ENABLED` also pointed at it. The recall win is
 * real and it is `b6d3d76b5`-shaped, not `4d98d9eab`-shaped.
 *
 * DO NOT COLLAPSE THIS INTO `isCodeShaped`. It looks like the same question and it is not,
 * because the two run over DIFFERENT POPULATIONS: `isCodeShaped` judges a token already
 * known to be a declaration NAME, while this one judges an arbitrary quoted span, which may
 * be prose someone quoted. Measured on the same 60 commits, delegating this test to
 * `isCodeShaped` gives rows 374 -> 408 (+9.1%, versus +2.4%) and admits `'unchanged.'`,
 * `'means.'` and `'version.'` — sentence fragments that reach `isCodeShaped`'s `.` arm.
 * Those three are pinned as non-anchors in `--self-test` so the collapse goes red.
 */
function isLiteralAnchorShape(lit) {
 return /^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/.test(lit) // snake_case
 || /^[a-z]+(?:[A-Z][A-Za-z0-9]*)+$/.test(lit) // camelCase
 || /^[a-z][a-z0-9]*(?:\.[a-z][A-Za-z0-9]*)+$/.test(lit) // a dotted client path
 || /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/.test(lit); // SCREAMING_SNAKE (#13471)
}

/** Route tails and identifier-shaped string literals appearing on the changed lines. */
function literalAnchorsFromLines(lines, changed) {
 const routes = new Set();
Expand DownExpand Up@@ -1266,9 +1324,7 @@ function literalAnchorsFromLines(lines, changed) {
 for (const m of line.matchAll(/['"]([A-Za-z][\w.$-]{3,63})['"]/g)) {
 const lit = m[1];
 if (GENERIC_ANCHOR_NAMES.has(lit.toLowerCase())) continue;
 // Identifier-shaped only: snake_case, camelCase or dotted. A quoted English word
 // ('ignore', 'utf8') is not a surface anyone documents by that spelling.
 if (!/^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/.test(lit) && !/^[a-z]+(?:[A-Z][A-Za-z0-9]*)+$/.test(lit) && !/^[a-z][a-z0-9]*(?:\.[a-z][A-Za-z0-9]*)+$/.test(lit)) continue;
 if (!isLiteralAnchorShape(lit)) continue;
 literals.add(lit);
 const where = enclosingName();
 noteFrom(from, lit, where ? `a string literal in ${where}` : 'a string literal on a changed line');
Expand DownExpand Up@@ -4348,15 +4404,50 @@ function selfTest() {
 check('PHRASE_ANCHOR_KINDS', 'a rule expression is distinctive by construction', 'rule', true, PHRASE_ANCHOR_KINDS.has('rule'));

 // String literals on a changed line: an identifier-shaped one is surface, English is not.
 const litLines = [" if (rule === 'controlled_by_parent') return maskFieldValue(v);", " fs.readFileSync(p, 'utf8');", " logger.warn('ignore');"];
 const lits = literalAnchorsFromLines(litLines, [1, 2, 3]).literals;
 const litLines = [" if (rule === 'controlled_by_parent') return maskFieldValue(v);", " fs.readFileSync(p, 'utf8');", " logger.warn('ignore');",
 " const ENV = 'OS_TENANCY_POSTURE';", " if (c === 'FLOW_NO_START_NODE') return refuse(c);",
 " // the shape is 'unchanged.' in that arm", " throw new Error('EEXIT');"];
 const lits = literalAnchorsFromLines(litLines, [1, 2, 3, 4, 5, 6, 7]).literals;
 const literalCases = [
 ['controlled_by_parent', true, 'a snake_case literal IS an authoring surface'],
 ['utf8', false, 'an encoding name is not surface'],
 ['ignore', false, 'an English word is not surface'],
 // #13471. The env-var name is the case the whole card was filed on: a page that names
 // env vars and essentially nothing else has no other `literal` route onto an advisory.
 ['OS_TENANCY_POSTURE', true, 'a SCREAMING_SNAKE env-var name IS an authoring surface'],
 ['FLOW_NO_START_NODE', true, 'and so is a refusal code — the measured recall win'],
 // ⛔ The guard rail on the widening, both halves measured on the same 60 commits.
 ['unchanged.', false, 'a quoted sentence fragment is still not surface'],
 ['EEXIT', false, 'a bare all-caps word is not SCREAMING_SNAKE — the shape needs a segment break'],
 ];
 for (const [lit, want, label] of literalCases) check('literalAnchorsFromLines', label, lit, want, lits.has(lit));

 // ── THE PAIR MUST AGREE ON SCREAMING_SNAKE (#13471) ──
 // The defect this closed was not "recall too low", it was TWO PREDICATES CONTRADICTING
 // each other with nothing reporting the split: `isCodeShaped` called `OS_MODE` an
 // identifier (pinned in `shapeCases` above) while `literalAnchorsFromLines` declined to
 // mint any anchor from it. Pin the agreement itself, so neither side can drift back out
 // of step silently — a check on one predicate alone could not have caught this.
 for (const t of ['OS_CLOUD_URL', 'OS_MODE', 'OS_TENANCY_POSTURE', 'ERROR_CODE_LEDGER', 'FLOW_INPUT_SCHEMA_INVALID']) {
 check('isCodeShaped/isLiteralAnchorShape', 'the pair agrees on a SCREAMING_SNAKE token', t,
 true, isCodeShaped(t) === isLiteralAnchorShape(t) && isLiteralAnchorShape(t));
 }

 // ⛔ AND THE DISAGREEMENTS THAT REMAIN ARE DELIBERATE, so the next reader does not
 // "finish the job" by collapsing this test into `isCodeShaped`. The two run over
 // DIFFERENT POPULATIONS — a declaration NAME versus an arbitrary quoted span that may be
 // prose — and delegating measured rows 374 -> 408 (+9.1%, versus +2.4% for the shape
 // above) on the same 60 commits. These three fragments are what it admits.
 const deliberateSplits = [
 ['unchanged.', 'a sentence fragment reaches isCodeShaped through its `.` arm'],
 ['means.', 'ditto — measured, not hypothetical'],
 ['version.', 'ditto'],
 ['IHttpRequest', 'a PascalCase name is already reachable through the `symbol` kind'],
 ];
 for (const [t, label] of deliberateSplits) {
 check('isCodeShaped/isLiteralAnchorShape', label, t, true, isCodeShaped(t) && !isLiteralAnchorShape(t));
 }

 // ── `computedOn` (#9519): the record that names WHICH TREE the answer is about ──
 // Pinned on the pure shaper, so these stay hermetic; the probing wrapper reads real
 // git state by construction. Two properties carry the field's whole value: a merge
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
docs-audit: let a SCREAMING_SNAKE literal mint an anchor, and pin the predicate pair#13782

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


docs-audit: let a SCREAMING_SNAKE literal mint an anchor, and pin the predicate pair
#13782
 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


101 changes: 96 additions & 5 deletions
scripts/docs-audit/affected-docs.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -1238,6 +1238,64 @@ function noteFrom(map, token, clause) {
 set.add(clause);
}

/**
 * Is this quoted span identifier-shaped enough to mint a `literal` anchor?
 *
 * FOUR SHAPES. Three of them say "an identifier starts lowercase" — snake_case,
 * camelCase, a dotted client path. A quoted English word (`'ignore'`, `'utf8'`) is not a
 * surface anyone documents by that spelling, and those three keep it out.
 *
 * THE FOURTH IS SCREAMING_SNAKE, AND IT IS HERE TO END A DISAGREEMENT (#13471). While the
 * three lowercase-initial shapes were the whole rule, this predicate and `isCodeShaped`
 * contradicted each other on every constant name: `isCodeShaped('OS_MODE')` is `true` —
 * pinned as `SCREAMING_SNAKE` in the shape cases below since the guard was written — while
 * this test declined to mint an anchor from it at all. One predicate in the pair called the
 * token an identifier, the other silently called it prose, and nothing reported the split.
 * A page that names env vars and essentially nothing else (`deployment/environment-variables.mdx`)
 * has no other `literal` route onto an advisory.
 *
 * The fourth shape is earned by the same argument that earns `PHRASE_ANCHOR_KINDS` its
 * exemption — DISTINCTIVE BY CONSTRUCTION, not by inspection. `OS_TENANCY_POSTURE` cannot
 * be the English word this guard exists to drop: prose does not shout in underscores. Note
 * the shape is MULTI-SEGMENT by construction (the `_` is required), so a bare all-caps word
 * is not admitted by it — see the deliberate-disagreement pins in `--self-test`.
 *
 * MEASURED BOTH WAYS before widening, over the 60 most recent `packages/**` commits, using
 * the per-row provenance #12824 published so each added row could be attributed to the
 * declaration that minted it rather than counted in a lump:
 * - rows 374 -> 383 (+9, +2.4%), and ZERO rows lost;
 * - `overbroadAnchors` 8 -> 8: the corpus-share guard caught no new hub term, so the
 * widening minted no term broad enough to need catching;
 * - only 2 of the 60 runs moved at all. Every new anchor named its declaration:
 * `FlowRefusalCode`, `AUTHZ_STORE_UNAVAILABLE_CODE`, `codes`.
 * - GROUND TRUTH on `b6d3d76b5`, whose own commit edited three docs pages: the advisory
 * went from 0 of those 3 (it listed two `releases/**` pages and nothing else) to 2 of 3
 * — `api/client-sdk.mdx` and `automation/flows.mdx`, both minted from `FlowRefusalCode`.
 * - the four vendor codes in that window (`ER_DUP_KEYNAME` and friends, from a MySQL
 * driver table) minted anchors and matched NO page, so they cost nothing: an anchor
 * no doc names is not a row.
 *
 * BLAST RADIUS, KEPT HONEST. `4d98d9eab` is the commit this was found on, and the widening
 * adds ZERO rows there: `environment-variables.mdx` was already listed through the `route`
 * anchor `/api/v1/runtime/config`, so all the fourth shape adds is a second `via` clause
 * saying `OS_TELEMETRY_CLIENT_ERROR_REPORTING_ENABLED` also pointed at it. The recall win is
 * real and it is `b6d3d76b5`-shaped, not `4d98d9eab`-shaped.
 *
 * DO NOT COLLAPSE THIS INTO `isCodeShaped`. It looks like the same question and it is not,
 * because the two run over DIFFERENT POPULATIONS: `isCodeShaped` judges a token already
 * known to be a declaration NAME, while this one judges an arbitrary quoted span, which may
 * be prose someone quoted. Measured on the same 60 commits, delegating this test to
 * `isCodeShaped` gives rows 374 -> 408 (+9.1%, versus +2.4%) and admits `'unchanged.'`,
 * `'means.'` and `'version.'` — sentence fragments that reach `isCodeShaped`'s `.` arm.
 * Those three are pinned as non-anchors in `--self-test` so the collapse goes red.
 */
function isLiteralAnchorShape(lit) {
 return /^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/.test(lit) // snake_case
 || /^[a-z]+(?:[A-Z][A-Za-z0-9]*)+$/.test(lit) // camelCase
 || /^[a-z][a-z0-9]*(?:\.[a-z][A-Za-z0-9]*)+$/.test(lit) // a dotted client path
 || /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/.test(lit); // SCREAMING_SNAKE (#13471)
}

/** Route tails and identifier-shaped string literals appearing on the changed lines. */
function literalAnchorsFromLines(lines, changed) {
 const routes = new Set();
Expand DownExpand Up@@ -1266,9 +1324,7 @@ function literalAnchorsFromLines(lines, changed) {
 for (const m of line.matchAll(/['"]([A-Za-z][\w.$-]{3,63})['"]/g)) {
 const lit = m[1];
 if (GENERIC_ANCHOR_NAMES.has(lit.toLowerCase())) continue;
 // Identifier-shaped only: snake_case, camelCase or dotted. A quoted English word
 // ('ignore', 'utf8') is not a surface anyone documents by that spelling.
 if (!/^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/.test(lit) && !/^[a-z]+(?:[A-Z][A-Za-z0-9]*)+$/.test(lit) && !/^[a-z][a-z0-9]*(?:\.[a-z][A-Za-z0-9]*)+$/.test(lit)) continue;
 if (!isLiteralAnchorShape(lit)) continue;
 literals.add(lit);
 const where = enclosingName();
 noteFrom(from, lit, where ? `a string literal in ${where}` : 'a string literal on a changed line');
Expand DownExpand Up@@ -4348,15 +4404,50 @@ function selfTest() {
 check('PHRASE_ANCHOR_KINDS', 'a rule expression is distinctive by construction', 'rule', true, PHRASE_ANCHOR_KINDS.has('rule'));

 // String literals on a changed line: an identifier-shaped one is surface, English is not.
 const litLines = [" if (rule === 'controlled_by_parent') return maskFieldValue(v);", " fs.readFileSync(p, 'utf8');", " logger.warn('ignore');"];
 const lits = literalAnchorsFromLines(litLines, [1, 2, 3]).literals;
 const litLines = [" if (rule === 'controlled_by_parent') return maskFieldValue(v);", " fs.readFileSync(p, 'utf8');", " logger.warn('ignore');",
 " const ENV = 'OS_TENANCY_POSTURE';", " if (c === 'FLOW_NO_START_NODE') return refuse(c);",
 " // the shape is 'unchanged.' in that arm", " throw new Error('EEXIT');"];
 const lits = literalAnchorsFromLines(litLines, [1, 2, 3, 4, 5, 6, 7]).literals;
 const literalCases = [
 ['controlled_by_parent', true, 'a snake_case literal IS an authoring surface'],
 ['utf8', false, 'an encoding name is not surface'],
 ['ignore', false, 'an English word is not surface'],
 // #13471. The env-var name is the case the whole card was filed on: a page that names
 // env vars and essentially nothing else has no other `literal` route onto an advisory.
 ['OS_TENANCY_POSTURE', true, 'a SCREAMING_SNAKE env-var name IS an authoring surface'],
 ['FLOW_NO_START_NODE', true, 'and so is a refusal code — the measured recall win'],
 // ⛔ The guard rail on the widening, both halves measured on the same 60 commits.
 ['unchanged.', false, 'a quoted sentence fragment is still not surface'],
 ['EEXIT', false, 'a bare all-caps word is not SCREAMING_SNAKE — the shape needs a segment break'],
 ];
 for (const [lit, want, label] of literalCases) check('literalAnchorsFromLines', label, lit, want, lits.has(lit));

 // ── THE PAIR MUST AGREE ON SCREAMING_SNAKE (#13471) ──
 // The defect this closed was not "recall too low", it was TWO PREDICATES CONTRADICTING
 // each other with nothing reporting the split: `isCodeShaped` called `OS_MODE` an
 // identifier (pinned in `shapeCases` above) while `literalAnchorsFromLines` declined to
 // mint any anchor from it. Pin the agreement itself, so neither side can drift back out
 // of step silently — a check on one predicate alone could not have caught this.
 for (const t of ['OS_CLOUD_URL', 'OS_MODE', 'OS_TENANCY_POSTURE', 'ERROR_CODE_LEDGER', 'FLOW_INPUT_SCHEMA_INVALID']) {
 check('isCodeShaped/isLiteralAnchorShape', 'the pair agrees on a SCREAMING_SNAKE token', t,
 true, isCodeShaped(t) === isLiteralAnchorShape(t) && isLiteralAnchorShape(t));
 }

 // ⛔ AND THE DISAGREEMENTS THAT REMAIN ARE DELIBERATE, so the next reader does not
 // "finish the job" by collapsing this test into `isCodeShaped`. The two run over
 // DIFFERENT POPULATIONS — a declaration NAME versus an arbitrary quoted span that may be
 // prose — and delegating measured rows 374 -> 408 (+9.1%, versus +2.4% for the shape
 // above) on the same 60 commits. These three fragments are what it admits.
 const deliberateSplits = [
 ['unchanged.', 'a sentence fragment reaches isCodeShaped through its `.` arm'],
 ['means.', 'ditto — measured, not hypothetical'],
 ['version.', 'ditto'],
 ['IHttpRequest', 'a PascalCase name is already reachable through the `symbol` kind'],
 ];
 for (const [t, label] of deliberateSplits) {
 check('isCodeShaped/isLiteralAnchorShape', label, t, true, isCodeShaped(t) && !isLiteralAnchorShape(t));
 }

 // ── `computedOn` (#9519): the record that names WHICH TREE the answer is about ──
 // Pinned on the pure shaper, so these stay hermetic; the probing wrapper reads real
 // git state by construction. Two properties carry the field's whole value: a merge
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
docs-audit: let a SCREAMING_SNAKE literal mint an anchor, and pin the predicate pair#13782

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


docs-audit: let a SCREAMING_SNAKE literal mint an anchor, and pin the predicate pair
#13782
 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


101 changes: 96 additions & 5 deletions
scripts/docs-audit/affected-docs.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -1238,6 +1238,64 @@ function noteFrom(map, token, clause) {
 set.add(clause);
}

/**
 * Is this quoted span identifier-shaped enough to mint a `literal` anchor?
 *
 * FOUR SHAPES. Three of them say "an identifier starts lowercase" — snake_case,
 * camelCase, a dotted client path. A quoted English word (`'ignore'`, `'utf8'`) is not a
 * surface anyone documents by that spelling, and those three keep it out.
 *
 * THE FOURTH IS SCREAMING_SNAKE, AND IT IS HERE TO END A DISAGREEMENT (#13471). While the
 * three lowercase-initial shapes were the whole rule, this predicate and `isCodeShaped`
 * contradicted each other on every constant name: `isCodeShaped('OS_MODE')` is `true` —
 * pinned as `SCREAMING_SNAKE` in the shape cases below since the guard was written — while
 * this test declined to mint an anchor from it at all. One predicate in the pair called the
 * token an identifier, the other silently called it prose, and nothing reported the split.
 * A page that names env vars and essentially nothing else (`deployment/environment-variables.mdx`)
 * has no other `literal` route onto an advisory.
 *
 * The fourth shape is earned by the same argument that earns `PHRASE_ANCHOR_KINDS` its
 * exemption — DISTINCTIVE BY CONSTRUCTION, not by inspection. `OS_TENANCY_POSTURE` cannot
 * be the English word this guard exists to drop: prose does not shout in underscores. Note
 * the shape is MULTI-SEGMENT by construction (the `_` is required), so a bare all-caps word
 * is not admitted by it — see the deliberate-disagreement pins in `--self-test`.
 *
 * MEASURED BOTH WAYS before widening, over the 60 most recent `packages/**` commits, using
 * the per-row provenance #12824 published so each added row could be attributed to the
 * declaration that minted it rather than counted in a lump:
 * - rows 374 -> 383 (+9, +2.4%), and ZERO rows lost;
 * - `overbroadAnchors` 8 -> 8: the corpus-share guard caught no new hub term, so the
 * widening minted no term broad enough to need catching;
 * - only 2 of the 60 runs moved at all. Every new anchor named its declaration:
 * `FlowRefusalCode`, `AUTHZ_STORE_UNAVAILABLE_CODE`, `codes`.
 * - GROUND TRUTH on `b6d3d76b5`, whose own commit edited three docs pages: the advisory
 * went from 0 of those 3 (it listed two `releases/**` pages and nothing else) to 2 of 3
 * — `api/client-sdk.mdx` and `automation/flows.mdx`, both minted from `FlowRefusalCode`.
 * - the four vendor codes in that window (`ER_DUP_KEYNAME` and friends, from a MySQL
 * driver table) minted anchors and matched NO page, so they cost nothing: an anchor
 * no doc names is not a row.
 *
 * BLAST RADIUS, KEPT HONEST. `4d98d9eab` is the commit this was found on, and the widening
 * adds ZERO rows there: `environment-variables.mdx` was already listed through the `route`
 * anchor `/api/v1/runtime/config`, so all the fourth shape adds is a second `via` clause
 * saying `OS_TELEMETRY_CLIENT_ERROR_REPORTING_ENABLED` also pointed at it. The recall win is
 * real and it is `b6d3d76b5`-shaped, not `4d98d9eab`-shaped.
 *
 * DO NOT COLLAPSE THIS INTO `isCodeShaped`. It looks like the same question and it is not,
 * because the two run over DIFFERENT POPULATIONS: `isCodeShaped` judges a token already
 * known to be a declaration NAME, while this one judges an arbitrary quoted span, which may
 * be prose someone quoted. Measured on the same 60 commits, delegating this test to
 * `isCodeShaped` gives rows 374 -> 408 (+9.1%, versus +2.4%) and admits `'unchanged.'`,
 * `'means.'` and `'version.'` — sentence fragments that reach `isCodeShaped`'s `.` arm.
 * Those three are pinned as non-anchors in `--self-test` so the collapse goes red.
 */
function isLiteralAnchorShape(lit) {
 return /^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/.test(lit) // snake_case
 || /^[a-z]+(?:[A-Z][A-Za-z0-9]*)+$/.test(lit) // camelCase
 || /^[a-z][a-z0-9]*(?:\.[a-z][A-Za-z0-9]*)+$/.test(lit) // a dotted client path
 || /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/.test(lit); // SCREAMING_SNAKE (#13471)
}

/** Route tails and identifier-shaped string literals appearing on the changed lines. */
function literalAnchorsFromLines(lines, changed) {
 const routes = new Set();
Expand DownExpand Up@@ -1266,9 +1324,7 @@ function literalAnchorsFromLines(lines, changed) {
 for (const m of line.matchAll(/['"]([A-Za-z][\w.$-]{3,63})['"]/g)) {
 const lit = m[1];
 if (GENERIC_ANCHOR_NAMES.has(lit.toLowerCase())) continue;
 // Identifier-shaped only: snake_case, camelCase or dotted. A quoted English word
 // ('ignore', 'utf8') is not a surface anyone documents by that spelling.
 if (!/^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/.test(lit) && !/^[a-z]+(?:[A-Z][A-Za-z0-9]*)+$/.test(lit) && !/^[a-z][a-z0-9]*(?:\.[a-z][A-Za-z0-9]*)+$/.test(lit)) continue;
 if (!isLiteralAnchorShape(lit)) continue;
 literals.add(lit);
 const where = enclosingName();
 noteFrom(from, lit, where ? `a string literal in ${where}` : 'a string literal on a changed line');
Expand DownExpand Up@@ -4348,15 +4404,50 @@ function selfTest() {
 check('PHRASE_ANCHOR_KINDS', 'a rule expression is distinctive by construction', 'rule', true, PHRASE_ANCHOR_KINDS.has('rule'));

 // String literals on a changed line: an identifier-shaped one is surface, English is not.
 const litLines = [" if (rule === 'controlled_by_parent') return maskFieldValue(v);", " fs.readFileSync(p, 'utf8');", " logger.warn('ignore');"];
 const lits = literalAnchorsFromLines(litLines, [1, 2, 3]).literals;
 const litLines = [" if (rule === 'controlled_by_parent') return maskFieldValue(v);", " fs.readFileSync(p, 'utf8');", " logger.warn('ignore');",
 " const ENV = 'OS_TENANCY_POSTURE';", " if (c === 'FLOW_NO_START_NODE') return refuse(c);",
 " // the shape is 'unchanged.' in that arm", " throw new Error('EEXIT');"];
 const lits = literalAnchorsFromLines(litLines, [1, 2, 3, 4, 5, 6, 7]).literals;
 const literalCases = [
 ['controlled_by_parent', true, 'a snake_case literal IS an authoring surface'],
 ['utf8', false, 'an encoding name is not surface'],
 ['ignore', false, 'an English word is not surface'],
 // #13471. The env-var name is the case the whole card was filed on: a page that names
 // env vars and essentially nothing else has no other `literal` route onto an advisory.
 ['OS_TENANCY_POSTURE', true, 'a SCREAMING_SNAKE env-var name IS an authoring surface'],
 ['FLOW_NO_START_NODE', true, 'and so is a refusal code — the measured recall win'],
 // ⛔ The guard rail on the widening, both halves measured on the same 60 commits.
 ['unchanged.', false, 'a quoted sentence fragment is still not surface'],
 ['EEXIT', false, 'a bare all-caps word is not SCREAMING_SNAKE — the shape needs a segment break'],
 ];
 for (const [lit, want, label] of literalCases) check('literalAnchorsFromLines', label, lit, want, lits.has(lit));

 // ── THE PAIR MUST AGREE ON SCREAMING_SNAKE (#13471) ──
 // The defect this closed was not "recall too low", it was TWO PREDICATES CONTRADICTING
 // each other with nothing reporting the split: `isCodeShaped` called `OS_MODE` an
 // identifier (pinned in `shapeCases` above) while `literalAnchorsFromLines` declined to
 // mint any anchor from it. Pin the agreement itself, so neither side can drift back out
 // of step silently — a check on one predicate alone could not have caught this.
 for (const t of ['OS_CLOUD_URL', 'OS_MODE', 'OS_TENANCY_POSTURE', 'ERROR_CODE_LEDGER', 'FLOW_INPUT_SCHEMA_INVALID']) {
 check('isCodeShaped/isLiteralAnchorShape', 'the pair agrees on a SCREAMING_SNAKE token', t,
 true, isCodeShaped(t) === isLiteralAnchorShape(t) && isLiteralAnchorShape(t));
 }

 // ⛔ AND THE DISAGREEMENTS THAT REMAIN ARE DELIBERATE, so the next reader does not
 // "finish the job" by collapsing this test into `isCodeShaped`. The two run over
 // DIFFERENT POPULATIONS — a declaration NAME versus an arbitrary quoted span that may be
 // prose — and delegating measured rows 374 -> 408 (+9.1%, versus +2.4% for the shape
 // above) on the same 60 commits. These three fragments are what it admits.
 const deliberateSplits = [
 ['unchanged.', 'a sentence fragment reaches isCodeShaped through its `.` arm'],
 ['means.', 'ditto — measured, not hypothetical'],
 ['version.', 'ditto'],
 ['IHttpRequest', 'a PascalCase name is already reachable through the `symbol` kind'],
 ];
 for (const [t, label] of deliberateSplits) {
 check('isCodeShaped/isLiteralAnchorShape', label, t, true, isCodeShaped(t) && !isLiteralAnchorShape(t));
 }

 // ── `computedOn` (#9519): the record that names WHICH TREE the answer is about ──
 // Pinned on the pure shaper, so these stay hermetic; the probing wrapper reads real
 // git state by construction. Two properties carry the field's whole value: a merge
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
docs-audit: let a SCREAMING_SNAKE literal mint an anchor, and pin the predicate pair#13782

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


docs-audit: let a SCREAMING_SNAKE literal mint an anchor, and pin the predicate pair
#13782
 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


101 changes: 96 additions & 5 deletions
scripts/docs-audit/affected-docs.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -1238,6 +1238,64 @@ function noteFrom(map, token, clause) {
 set.add(clause);
}

/**
 * Is this quoted span identifier-shaped enough to mint a `literal` anchor?
 *
 * FOUR SHAPES. Three of them say "an identifier starts lowercase" — snake_case,
 * camelCase, a dotted client path. A quoted English word (`'ignore'`, `'utf8'`) is not a
 * surface anyone documents by that spelling, and those three keep it out.
 *
 * THE FOURTH IS SCREAMING_SNAKE, AND IT IS HERE TO END A DISAGREEMENT (#13471). While the
 * three lowercase-initial shapes were the whole rule, this predicate and `isCodeShaped`
 * contradicted each other on every constant name: `isCodeShaped('OS_MODE')` is `true` —
 * pinned as `SCREAMING_SNAKE` in the shape cases below since the guard was written — while
 * this test declined to mint an anchor from it at all. One predicate in the pair called the
 * token an identifier, the other silently called it prose, and nothing reported the split.
 * A page that names env vars and essentially nothing else (`deployment/environment-variables.mdx`)
 * has no other `literal` route onto an advisory.
 *
 * The fourth shape is earned by the same argument that earns `PHRASE_ANCHOR_KINDS` its
 * exemption — DISTINCTIVE BY CONSTRUCTION, not by inspection. `OS_TENANCY_POSTURE` cannot
 * be the English word this guard exists to drop: prose does not shout in underscores. Note
 * the shape is MULTI-SEGMENT by construction (the `_` is required), so a bare all-caps word
 * is not admitted by it — see the deliberate-disagreement pins in `--self-test`.
 *
 * MEASURED BOTH WAYS before widening, over the 60 most recent `packages/**` commits, using
 * the per-row provenance #12824 published so each added row could be attributed to the
 * declaration that minted it rather than counted in a lump:
 * - rows 374 -> 383 (+9, +2.4%), and ZERO rows lost;
 * - `overbroadAnchors` 8 -> 8: the corpus-share guard caught no new hub term, so the
 * widening minted no term broad enough to need catching;
 * - only 2 of the 60 runs moved at all. Every new anchor named its declaration:
 * `FlowRefusalCode`, `AUTHZ_STORE_UNAVAILABLE_CODE`, `codes`.
 * - GROUND TRUTH on `b6d3d76b5`, whose own commit edited three docs pages: the advisory
 * went from 0 of those 3 (it listed two `releases/**` pages and nothing else) to 2 of 3
 * — `api/client-sdk.mdx` and `automation/flows.mdx`, both minted from `FlowRefusalCode`.
 * - the four vendor codes in that window (`ER_DUP_KEYNAME` and friends, from a MySQL
 * driver table) minted anchors and matched NO page, so they cost nothing: an anchor
 * no doc names is not a row.
 *
 * BLAST RADIUS, KEPT HONEST. `4d98d9eab` is the commit this was found on, and the widening
 * adds ZERO rows there: `environment-variables.mdx` was already listed through the `route`
 * anchor `/api/v1/runtime/config`, so all the fourth shape adds is a second `via` clause
 * saying `OS_TELEMETRY_CLIENT_ERROR_REPORTING_ENABLED` also pointed at it. The recall win is
 * real and it is `b6d3d76b5`-shaped, not `4d98d9eab`-shaped.
 *
 * DO NOT COLLAPSE THIS INTO `isCodeShaped`. It looks like the same question and it is not,
 * because the two run over DIFFERENT POPULATIONS: `isCodeShaped` judges a token already
 * known to be a declaration NAME, while this one judges an arbitrary quoted span, which may
 * be prose someone quoted. Measured on the same 60 commits, delegating this test to
 * `isCodeShaped` gives rows 374 -> 408 (+9.1%, versus +2.4%) and admits `'unchanged.'`,
 * `'means.'` and `'version.'` — sentence fragments that reach `isCodeShaped`'s `.` arm.
 * Those three are pinned as non-anchors in `--self-test` so the collapse goes red.
 */
function isLiteralAnchorShape(lit) {
 return /^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/.test(lit) // snake_case
 || /^[a-z]+(?:[A-Z][A-Za-z0-9]*)+$/.test(lit) // camelCase
 || /^[a-z][a-z0-9]*(?:\.[a-z][A-Za-z0-9]*)+$/.test(lit) // a dotted client path
 || /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/.test(lit); // SCREAMING_SNAKE (#13471)
}

/** Route tails and identifier-shaped string literals appearing on the changed lines. */
function literalAnchorsFromLines(lines, changed) {
 const routes = new Set();
Expand DownExpand Up@@ -1266,9 +1324,7 @@ function literalAnchorsFromLines(lines, changed) {
 for (const m of line.matchAll(/['"]([A-Za-z][\w.$-]{3,63})['"]/g)) {
 const lit = m[1];
 if (GENERIC_ANCHOR_NAMES.has(lit.toLowerCase())) continue;
 // Identifier-shaped only: snake_case, camelCase or dotted. A quoted English word
 // ('ignore', 'utf8') is not a surface anyone documents by that spelling.
 if (!/^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/.test(lit) && !/^[a-z]+(?:[A-Z][A-Za-z0-9]*)+$/.test(lit) && !/^[a-z][a-z0-9]*(?:\.[a-z][A-Za-z0-9]*)+$/.test(lit)) continue;
 if (!isLiteralAnchorShape(lit)) continue;
 literals.add(lit);
 const where = enclosingName();
 noteFrom(from, lit, where ? `a string literal in ${where}` : 'a string literal on a changed line');
Expand DownExpand Up@@ -4348,15 +4404,50 @@ function selfTest() {
 check('PHRASE_ANCHOR_KINDS', 'a rule expression is distinctive by construction', 'rule', true, PHRASE_ANCHOR_KINDS.has('rule'));

 // String literals on a changed line: an identifier-shaped one is surface, English is not.
 const litLines = [" if (rule === 'controlled_by_parent') return maskFieldValue(v);", " fs.readFileSync(p, 'utf8');", " logger.warn('ignore');"];
 const lits = literalAnchorsFromLines(litLines, [1, 2, 3]).literals;
 const litLines = [" if (rule === 'controlled_by_parent') return maskFieldValue(v);", " fs.readFileSync(p, 'utf8');", " logger.warn('ignore');",
 " const ENV = 'OS_TENANCY_POSTURE';", " if (c === 'FLOW_NO_START_NODE') return refuse(c);",
 " // the shape is 'unchanged.' in that arm", " throw new Error('EEXIT');"];
 const lits = literalAnchorsFromLines(litLines, [1, 2, 3, 4, 5, 6, 7]).literals;
 const literalCases = [
 ['controlled_by_parent', true, 'a snake_case literal IS an authoring surface'],
 ['utf8', false, 'an encoding name is not surface'],
 ['ignore', false, 'an English word is not surface'],
 // #13471. The env-var name is the case the whole card was filed on: a page that names
 // env vars and essentially nothing else has no other `literal` route onto an advisory.
 ['OS_TENANCY_POSTURE', true, 'a SCREAMING_SNAKE env-var name IS an authoring surface'],
 ['FLOW_NO_START_NODE', true, 'and so is a refusal code — the measured recall win'],
 // ⛔ The guard rail on the widening, both halves measured on the same 60 commits.
 ['unchanged.', false, 'a quoted sentence fragment is still not surface'],
 ['EEXIT', false, 'a bare all-caps word is not SCREAMING_SNAKE — the shape needs a segment break'],
 ];
 for (const [lit, want, label] of literalCases) check('literalAnchorsFromLines', label, lit, want, lits.has(lit));

 // ── THE PAIR MUST AGREE ON SCREAMING_SNAKE (#13471) ──
 // The defect this closed was not "recall too low", it was TWO PREDICATES CONTRADICTING
 // each other with nothing reporting the split: `isCodeShaped` called `OS_MODE` an
 // identifier (pinned in `shapeCases` above) while `literalAnchorsFromLines` declined to
 // mint any anchor from it. Pin the agreement itself, so neither side can drift back out
 // of step silently — a check on one predicate alone could not have caught this.
 for (const t of ['OS_CLOUD_URL', 'OS_MODE', 'OS_TENANCY_POSTURE', 'ERROR_CODE_LEDGER', 'FLOW_INPUT_SCHEMA_INVALID']) {
 check('isCodeShaped/isLiteralAnchorShape', 'the pair agrees on a SCREAMING_SNAKE token', t,
 true, isCodeShaped(t) === isLiteralAnchorShape(t) && isLiteralAnchorShape(t));
 }

 // ⛔ AND THE DISAGREEMENTS THAT REMAIN ARE DELIBERATE, so the next reader does not
 // "finish the job" by collapsing this test into `isCodeShaped`. The two run over
 // DIFFERENT POPULATIONS — a declaration NAME versus an arbitrary quoted span that may be
 // prose — and delegating measured rows 374 -> 408 (+9.1%, versus +2.4% for the shape
 // above) on the same 60 commits. These three fragments are what it admits.
 const deliberateSplits = [
 ['unchanged.', 'a sentence fragment reaches isCodeShaped through its `.` arm'],
 ['means.', 'ditto — measured, not hypothetical'],
 ['version.', 'ditto'],
 ['IHttpRequest', 'a PascalCase name is already reachable through the `symbol` kind'],
 ];
 for (const [t, label] of deliberateSplits) {
 check('isCodeShaped/isLiteralAnchorShape', label, t, true, isCodeShaped(t) && !isLiteralAnchorShape(t));
 }

 // ── `computedOn` (#9519): the record that names WHICH TREE the answer is about ──
 // Pinned on the pure shaper, so these stay hermetic; the probing wrapper reads real
 // git state by construction. Two properties carry the field's whole value: a merge
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
docs-audit: let a SCREAMING_SNAKE literal mint an anchor, and pin the predicate pair#13782

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


docs-audit: let a SCREAMING_SNAKE literal mint an anchor, and pin the predicate pair
#13782
 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


101 changes: 96 additions & 5 deletions
scripts/docs-audit/affected-docs.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -1238,6 +1238,64 @@ function noteFrom(map, token, clause) {
 set.add(clause);
}

/**
 * Is this quoted span identifier-shaped enough to mint a `literal` anchor?
 *
 * FOUR SHAPES. Three of them say "an identifier starts lowercase" — snake_case,
 * camelCase, a dotted client path. A quoted English word (`'ignore'`, `'utf8'`) is not a
 * surface anyone documents by that spelling, and those three keep it out.
 *
 * THE FOURTH IS SCREAMING_SNAKE, AND IT IS HERE TO END A DISAGREEMENT (#13471). While the
 * three lowercase-initial shapes were the whole rule, this predicate and `isCodeShaped`
 * contradicted each other on every constant name: `isCodeShaped('OS_MODE')` is `true` —
 * pinned as `SCREAMING_SNAKE` in the shape cases below since the guard was written — while
 * this test declined to mint an anchor from it at all. One predicate in the pair called the
 * token an identifier, the other silently called it prose, and nothing reported the split.
 * A page that names env vars and essentially nothing else (`deployment/environment-variables.mdx`)
 * has no other `literal` route onto an advisory.
 *
 * The fourth shape is earned by the same argument that earns `PHRASE_ANCHOR_KINDS` its
 * exemption — DISTINCTIVE BY CONSTRUCTION, not by inspection. `OS_TENANCY_POSTURE` cannot
 * be the English word this guard exists to drop: prose does not shout in underscores. Note
 * the shape is MULTI-SEGMENT by construction (the `_` is required), so a bare all-caps word
 * is not admitted by it — see the deliberate-disagreement pins in `--self-test`.
 *
 * MEASURED BOTH WAYS before widening, over the 60 most recent `packages/**` commits, using
 * the per-row provenance #12824 published so each added row could be attributed to the
 * declaration that minted it rather than counted in a lump:
 * - rows 374 -> 383 (+9, +2.4%), and ZERO rows lost;
 * - `overbroadAnchors` 8 -> 8: the corpus-share guard caught no new hub term, so the
 * widening minted no term broad enough to need catching;
 * - only 2 of the 60 runs moved at all. Every new anchor named its declaration:
 * `FlowRefusalCode`, `AUTHZ_STORE_UNAVAILABLE_CODE`, `codes`.
 * - GROUND TRUTH on `b6d3d76b5`, whose own commit edited three docs pages: the advisory
 * went from 0 of those 3 (it listed two `releases/**` pages and nothing else) to 2 of 3
 * — `api/client-sdk.mdx` and `automation/flows.mdx`, both minted from `FlowRefusalCode`.
 * - the four vendor codes in that window (`ER_DUP_KEYNAME` and friends, from a MySQL
 * driver table) minted anchors and matched NO page, so they cost nothing: an anchor
 * no doc names is not a row.
 *
 * BLAST RADIUS, KEPT HONEST. `4d98d9eab` is the commit this was found on, and the widening
 * adds ZERO rows there: `environment-variables.mdx` was already listed through the `route`
 * anchor `/api/v1/runtime/config`, so all the fourth shape adds is a second `via` clause
 * saying `OS_TELEMETRY_CLIENT_ERROR_REPORTING_ENABLED` also pointed at it. The recall win is
 * real and it is `b6d3d76b5`-shaped, not `4d98d9eab`-shaped.
 *
 * DO NOT COLLAPSE THIS INTO `isCodeShaped`. It looks like the same question and it is not,
 * because the two run over DIFFERENT POPULATIONS: `isCodeShaped` judges a token already
 * known to be a declaration NAME, while this one judges an arbitrary quoted span, which may
 * be prose someone quoted. Measured on the same 60 commits, delegating this test to
 * `isCodeShaped` gives rows 374 -> 408 (+9.1%, versus +2.4%) and admits `'unchanged.'`,
 * `'means.'` and `'version.'` — sentence fragments that reach `isCodeShaped`'s `.` arm.
 * Those three are pinned as non-anchors in `--self-test` so the collapse goes red.
 */
function isLiteralAnchorShape(lit) {
 return /^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/.test(lit) // snake_case
 || /^[a-z]+(?:[A-Z][A-Za-z0-9]*)+$/.test(lit) // camelCase
 || /^[a-z][a-z0-9]*(?:\.[a-z][A-Za-z0-9]*)+$/.test(lit) // a dotted client path
 || /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/.test(lit); // SCREAMING_SNAKE (#13471)
}

/** Route tails and identifier-shaped string literals appearing on the changed lines. */
function literalAnchorsFromLines(lines, changed) {
 const routes = new Set();
Expand DownExpand Up@@ -1266,9 +1324,7 @@ function literalAnchorsFromLines(lines, changed) {
 for (const m of line.matchAll(/['"]([A-Za-z][\w.$-]{3,63})['"]/g)) {
 const lit = m[1];
 if (GENERIC_ANCHOR_NAMES.has(lit.toLowerCase())) continue;
 // Identifier-shaped only: snake_case, camelCase or dotted. A quoted English word
 // ('ignore', 'utf8') is not a surface anyone documents by that spelling.
 if (!/^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/.test(lit) && !/^[a-z]+(?:[A-Z][A-Za-z0-9]*)+$/.test(lit) && !/^[a-z][a-z0-9]*(?:\.[a-z][A-Za-z0-9]*)+$/.test(lit)) continue;
 if (!isLiteralAnchorShape(lit)) continue;
 literals.add(lit);
 const where = enclosingName();
 noteFrom(from, lit, where ? `a string literal in ${where}` : 'a string literal on a changed line');
Expand DownExpand Up@@ -4348,15 +4404,50 @@ function selfTest() {
 check('PHRASE_ANCHOR_KINDS', 'a rule expression is distinctive by construction', 'rule', true, PHRASE_ANCHOR_KINDS.has('rule'));

 // String literals on a changed line: an identifier-shaped one is surface, English is not.
 const litLines = [" if (rule === 'controlled_by_parent') return maskFieldValue(v);", " fs.readFileSync(p, 'utf8');", " logger.warn('ignore');"];
 const lits = literalAnchorsFromLines(litLines, [1, 2, 3]).literals;
 const litLines = [" if (rule === 'controlled_by_parent') return maskFieldValue(v);", " fs.readFileSync(p, 'utf8');", " logger.warn('ignore');",
 " const ENV = 'OS_TENANCY_POSTURE';", " if (c === 'FLOW_NO_START_NODE') return refuse(c);",
 " // the shape is 'unchanged.' in that arm", " throw new Error('EEXIT');"];
 const lits = literalAnchorsFromLines(litLines, [1, 2, 3, 4, 5, 6, 7]).literals;
 const literalCases = [
 ['controlled_by_parent', true, 'a snake_case literal IS an authoring surface'],
 ['utf8', false, 'an encoding name is not surface'],
 ['ignore', false, 'an English word is not surface'],
 // #13471. The env-var name is the case the whole card was filed on: a page that names
 // env vars and essentially nothing else has no other `literal` route onto an advisory.
 ['OS_TENANCY_POSTURE', true, 'a SCREAMING_SNAKE env-var name IS an authoring surface'],
 ['FLOW_NO_START_NODE', true, 'and so is a refusal code — the measured recall win'],
 // ⛔ The guard rail on the widening, both halves measured on the same 60 commits.
 ['unchanged.', false, 'a quoted sentence fragment is still not surface'],
 ['EEXIT', false, 'a bare all-caps word is not SCREAMING_SNAKE — the shape needs a segment break'],
 ];
 for (const [lit, want, label] of literalCases) check('literalAnchorsFromLines', label, lit, want, lits.has(lit));

 // ── THE PAIR MUST AGREE ON SCREAMING_SNAKE (#13471) ──
 // The defect this closed was not "recall too low", it was TWO PREDICATES CONTRADICTING
 // each other with nothing reporting the split: `isCodeShaped` called `OS_MODE` an
 // identifier (pinned in `shapeCases` above) while `literalAnchorsFromLines` declined to
 // mint any anchor from it. Pin the agreement itself, so neither side can drift back out
 // of step silently — a check on one predicate alone could not have caught this.
 for (const t of ['OS_CLOUD_URL', 'OS_MODE', 'OS_TENANCY_POSTURE', 'ERROR_CODE_LEDGER', 'FLOW_INPUT_SCHEMA_INVALID']) {
 check('isCodeShaped/isLiteralAnchorShape', 'the pair agrees on a SCREAMING_SNAKE token', t,
 true, isCodeShaped(t) === isLiteralAnchorShape(t) && isLiteralAnchorShape(t));
 }

 // ⛔ AND THE DISAGREEMENTS THAT REMAIN ARE DELIBERATE, so the next reader does not
 // "finish the job" by collapsing this test into `isCodeShaped`. The two run over
 // DIFFERENT POPULATIONS — a declaration NAME versus an arbitrary quoted span that may be
 // prose — and delegating measured rows 374 -> 408 (+9.1%, versus +2.4% for the shape
 // above) on the same 60 commits. These three fragments are what it admits.
 const deliberateSplits = [
 ['unchanged.', 'a sentence fragment reaches isCodeShaped through its `.` arm'],
 ['means.', 'ditto — measured, not hypothetical'],
 ['version.', 'ditto'],
 ['IHttpRequest', 'a PascalCase name is already reachable through the `symbol` kind'],
 ];
 for (const [t, label] of deliberateSplits) {
 check('isCodeShaped/isLiteralAnchorShape', label, t, true, isCodeShaped(t) && !isLiteralAnchorShape(t));
 }

 // ── `computedOn` (#9519): the record that names WHICH TREE the answer is about ──
 // Pinned on the pure shaper, so these stay hermetic; the probing wrapper reads real
 // git state by construction. Two properties carry the field's whole value: a merge
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
docs-audit: let a SCREAMING_SNAKE literal mint an anchor, and pin the predicate pair#13782

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


docs-audit: let a SCREAMING_SNAKE literal mint an anchor, and pin the predicate pair
#13782
 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


101 changes: 96 additions & 5 deletions
scripts/docs-audit/affected-docs.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -1238,6 +1238,64 @@ function noteFrom(map, token, clause) {
 set.add(clause);
}

/**
 * Is this quoted span identifier-shaped enough to mint a `literal` anchor?
 *
 * FOUR SHAPES. Three of them say "an identifier starts lowercase" — snake_case,
 * camelCase, a dotted client path. A quoted English word (`'ignore'`, `'utf8'`) is not a
 * surface anyone documents by that spelling, and those three keep it out.
 *
 * THE FOURTH IS SCREAMING_SNAKE, AND IT IS HERE TO END A DISAGREEMENT (#13471). While the
 * three lowercase-initial shapes were the whole rule, this predicate and `isCodeShaped`
 * contradicted each other on every constant name: `isCodeShaped('OS_MODE')` is `true` —
 * pinned as `SCREAMING_SNAKE` in the shape cases below since the guard was written — while
 * this test declined to mint an anchor from it at all. One predicate in the pair called the
 * token an identifier, the other silently called it prose, and nothing reported the split.
 * A page that names env vars and essentially nothing else (`deployment/environment-variables.mdx`)
 * has no other `literal` route onto an advisory.
 *
 * The fourth shape is earned by the same argument that earns `PHRASE_ANCHOR_KINDS` its
 * exemption — DISTINCTIVE BY CONSTRUCTION, not by inspection. `OS_TENANCY_POSTURE` cannot
 * be the English word this guard exists to drop: prose does not shout in underscores. Note
 * the shape is MULTI-SEGMENT by construction (the `_` is required), so a bare all-caps word
 * is not admitted by it — see the deliberate-disagreement pins in `--self-test`.
 *
 * MEASURED BOTH WAYS before widening, over the 60 most recent `packages/**` commits, using
 * the per-row provenance #12824 published so each added row could be attributed to the
 * declaration that minted it rather than counted in a lump:
 * - rows 374 -> 383 (+9, +2.4%), and ZERO rows lost;
 * - `overbroadAnchors` 8 -> 8: the corpus-share guard caught no new hub term, so the
 * widening minted no term broad enough to need catching;
 * - only 2 of the 60 runs moved at all. Every new anchor named its declaration:
 * `FlowRefusalCode`, `AUTHZ_STORE_UNAVAILABLE_CODE`, `codes`.
 * - GROUND TRUTH on `b6d3d76b5`, whose own commit edited three docs pages: the advisory
 * went from 0 of those 3 (it listed two `releases/**` pages and nothing else) to 2 of 3
 * — `api/client-sdk.mdx` and `automation/flows.mdx`, both minted from `FlowRefusalCode`.
 * - the four vendor codes in that window (`ER_DUP_KEYNAME` and friends, from a MySQL
 * driver table) minted anchors and matched NO page, so they cost nothing: an anchor
 * no doc names is not a row.
 *
 * BLAST RADIUS, KEPT HONEST. `4d98d9eab` is the commit this was found on, and the widening
 * adds ZERO rows there: `environment-variables.mdx` was already listed through the `route`
 * anchor `/api/v1/runtime/config`, so all the fourth shape adds is a second `via` clause
 * saying `OS_TELEMETRY_CLIENT_ERROR_REPORTING_ENABLED` also pointed at it. The recall win is
 * real and it is `b6d3d76b5`-shaped, not `4d98d9eab`-shaped.
 *
 * DO NOT COLLAPSE THIS INTO `isCodeShaped`. It looks like the same question and it is not,
 * because the two run over DIFFERENT POPULATIONS: `isCodeShaped` judges a token already
 * known to be a declaration NAME, while this one judges an arbitrary quoted span, which may
 * be prose someone quoted. Measured on the same 60 commits, delegating this test to
 * `isCodeShaped` gives rows 374 -> 408 (+9.1%, versus +2.4%) and admits `'unchanged.'`,
 * `'means.'` and `'version.'` — sentence fragments that reach `isCodeShaped`'s `.` arm.
 * Those three are pinned as non-anchors in `--self-test` so the collapse goes red.
 */
function isLiteralAnchorShape(lit) {
 return /^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/.test(lit) // snake_case
 || /^[a-z]+(?:[A-Z][A-Za-z0-9]*)+$/.test(lit) // camelCase
 || /^[a-z][a-z0-9]*(?:\.[a-z][A-Za-z0-9]*)+$/.test(lit) // a dotted client path
 || /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/.test(lit); // SCREAMING_SNAKE (#13471)
}

/** Route tails and identifier-shaped string literals appearing on the changed lines. */
function literalAnchorsFromLines(lines, changed) {
 const routes = new Set();
Expand DownExpand Up@@ -1266,9 +1324,7 @@ function literalAnchorsFromLines(lines, changed) {
 for (const m of line.matchAll(/['"]([A-Za-z][\w.$-]{3,63})['"]/g)) {
 const lit = m[1];
 if (GENERIC_ANCHOR_NAMES.has(lit.toLowerCase())) continue;
 // Identifier-shaped only: snake_case, camelCase or dotted. A quoted English word
 // ('ignore', 'utf8') is not a surface anyone documents by that spelling.
 if (!/^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/.test(lit) && !/^[a-z]+(?:[A-Z][A-Za-z0-9]*)+$/.test(lit) && !/^[a-z][a-z0-9]*(?:\.[a-z][A-Za-z0-9]*)+$/.test(lit)) continue;
 if (!isLiteralAnchorShape(lit)) continue;
 literals.add(lit);
 const where = enclosingName();
 noteFrom(from, lit, where ? `a string literal in ${where}` : 'a string literal on a changed line');
Expand DownExpand Up@@ -4348,15 +4404,50 @@ function selfTest() {
 check('PHRASE_ANCHOR_KINDS', 'a rule expression is distinctive by construction', 'rule', true, PHRASE_ANCHOR_KINDS.has('rule'));

 // String literals on a changed line: an identifier-shaped one is surface, English is not.
 const litLines = [" if (rule === 'controlled_by_parent') return maskFieldValue(v);", " fs.readFileSync(p, 'utf8');", " logger.warn('ignore');"];
 const lits = literalAnchorsFromLines(litLines, [1, 2, 3]).literals;
 const litLines = [" if (rule === 'controlled_by_parent') return maskFieldValue(v);", " fs.readFileSync(p, 'utf8');", " logger.warn('ignore');",
 " const ENV = 'OS_TENANCY_POSTURE';", " if (c === 'FLOW_NO_START_NODE') return refuse(c);",
 " // the shape is 'unchanged.' in that arm", " throw new Error('EEXIT');"];
 const lits = literalAnchorsFromLines(litLines, [1, 2, 3, 4, 5, 6, 7]).literals;
 const literalCases = [
 ['controlled_by_parent', true, 'a snake_case literal IS an authoring surface'],
 ['utf8', false, 'an encoding name is not surface'],
 ['ignore', false, 'an English word is not surface'],
 // #13471. The env-var name is the case the whole card was filed on: a page that names
 // env vars and essentially nothing else has no other `literal` route onto an advisory.
 ['OS_TENANCY_POSTURE', true, 'a SCREAMING_SNAKE env-var name IS an authoring surface'],
 ['FLOW_NO_START_NODE', true, 'and so is a refusal code — the measured recall win'],
 // ⛔ The guard rail on the widening, both halves measured on the same 60 commits.
 ['unchanged.', false, 'a quoted sentence fragment is still not surface'],
 ['EEXIT', false, 'a bare all-caps word is not SCREAMING_SNAKE — the shape needs a segment break'],
 ];
 for (const [lit, want, label] of literalCases) check('literalAnchorsFromLines', label, lit, want, lits.has(lit));

 // ── THE PAIR MUST AGREE ON SCREAMING_SNAKE (#13471) ──
 // The defect this closed was not "recall too low", it was TWO PREDICATES CONTRADICTING
 // each other with nothing reporting the split: `isCodeShaped` called `OS_MODE` an
 // identifier (pinned in `shapeCases` above) while `literalAnchorsFromLines` declined to
 // mint any anchor from it. Pin the agreement itself, so neither side can drift back out
 // of step silently — a check on one predicate alone could not have caught this.
 for (const t of ['OS_CLOUD_URL', 'OS_MODE', 'OS_TENANCY_POSTURE', 'ERROR_CODE_LEDGER', 'FLOW_INPUT_SCHEMA_INVALID']) {
 check('isCodeShaped/isLiteralAnchorShape', 'the pair agrees on a SCREAMING_SNAKE token', t,
 true, isCodeShaped(t) === isLiteralAnchorShape(t) && isLiteralAnchorShape(t));
 }

 // ⛔ AND THE DISAGREEMENTS THAT REMAIN ARE DELIBERATE, so the next reader does not
 // "finish the job" by collapsing this test into `isCodeShaped`. The two run over
 // DIFFERENT POPULATIONS — a declaration NAME versus an arbitrary quoted span that may be
 // prose — and delegating measured rows 374 -> 408 (+9.1%, versus +2.4% for the shape
 // above) on the same 60 commits. These three fragments are what it admits.
 const deliberateSplits = [
 ['unchanged.', 'a sentence fragment reaches isCodeShaped through its `.` arm'],
 ['means.', 'ditto — measured, not hypothetical'],
 ['version.', 'ditto'],
 ['IHttpRequest', 'a PascalCase name is already reachable through the `symbol` kind'],
 ];
 for (const [t, label] of deliberateSplits) {
 check('isCodeShaped/isLiteralAnchorShape', label, t, true, isCodeShaped(t) && !isLiteralAnchorShape(t));
 }

 // ── `computedOn` (#9519): the record that names WHICH TREE the answer is about ──
 // Pinned on the pure shaper, so these stay hermetic; the probing wrapper reads real
 // git state by construction. Two properties carry the field's whole value: a merge
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
docs-audit: let a SCREAMING_SNAKE literal mint an anchor, and pin the predicate pair#13782

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


docs-audit: let a SCREAMING_SNAKE literal mint an anchor, and pin the predicate pair
#13782
 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


101 changes: 96 additions & 5 deletions
scripts/docs-audit/affected-docs.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -1238,6 +1238,64 @@ function noteFrom(map, token, clause) {
 set.add(clause);
}

/**
 * Is this quoted span identifier-shaped enough to mint a `literal` anchor?
 *
 * FOUR SHAPES. Three of them say "an identifier starts lowercase" — snake_case,
 * camelCase, a dotted client path. A quoted English word (`'ignore'`, `'utf8'`) is not a
 * surface anyone documents by that spelling, and those three keep it out.
 *
 * THE FOURTH IS SCREAMING_SNAKE, AND IT IS HERE TO END A DISAGREEMENT (#13471). While the
 * three lowercase-initial shapes were the whole rule, this predicate and `isCodeShaped`
 * contradicted each other on every constant name: `isCodeShaped('OS_MODE')` is `true` —
 * pinned as `SCREAMING_SNAKE` in the shape cases below since the guard was written — while
 * this test declined to mint an anchor from it at all. One predicate in the pair called the
 * token an identifier, the other silently called it prose, and nothing reported the split.
 * A page that names env vars and essentially nothing else (`deployment/environment-variables.mdx`)
 * has no other `literal` route onto an advisory.
 *
 * The fourth shape is earned by the same argument that earns `PHRASE_ANCHOR_KINDS` its
 * exemption — DISTINCTIVE BY CONSTRUCTION, not by inspection. `OS_TENANCY_POSTURE` cannot
 * be the English word this guard exists to drop: prose does not shout in underscores. Note
 * the shape is MULTI-SEGMENT by construction (the `_` is required), so a bare all-caps word
 * is not admitted by it — see the deliberate-disagreement pins in `--self-test`.
 *
 * MEASURED BOTH WAYS before widening, over the 60 most recent `packages/**` commits, using
 * the per-row provenance #12824 published so each added row could be attributed to the
 * declaration that minted it rather than counted in a lump:
 * - rows 374 -> 383 (+9, +2.4%), and ZERO rows lost;
 * - `overbroadAnchors` 8 -> 8: the corpus-share guard caught no new hub term, so the
 * widening minted no term broad enough to need catching;
 * - only 2 of the 60 runs moved at all. Every new anchor named its declaration:
 * `FlowRefusalCode`, `AUTHZ_STORE_UNAVAILABLE_CODE`, `codes`.
 * - GROUND TRUTH on `b6d3d76b5`, whose own commit edited three docs pages: the advisory
 * went from 0 of those 3 (it listed two `releases/**` pages and nothing else) to 2 of 3
 * — `api/client-sdk.mdx` and `automation/flows.mdx`, both minted from `FlowRefusalCode`.
 * - the four vendor codes in that window (`ER_DUP_KEYNAME` and friends, from a MySQL
 * driver table) minted anchors and matched NO page, so they cost nothing: an anchor
 * no doc names is not a row.
 *
 * BLAST RADIUS, KEPT HONEST. `4d98d9eab` is the commit this was found on, and the widening
 * adds ZERO rows there: `environment-variables.mdx` was already listed through the `route`
 * anchor `/api/v1/runtime/config`, so all the fourth shape adds is a second `via` clause
 * saying `OS_TELEMETRY_CLIENT_ERROR_REPORTING_ENABLED` also pointed at it. The recall win is
 * real and it is `b6d3d76b5`-shaped, not `4d98d9eab`-shaped.
 *
 * DO NOT COLLAPSE THIS INTO `isCodeShaped`. It looks like the same question and it is not,
 * because the two run over DIFFERENT POPULATIONS: `isCodeShaped` judges a token already
 * known to be a declaration NAME, while this one judges an arbitrary quoted span, which may
 * be prose someone quoted. Measured on the same 60 commits, delegating this test to
 * `isCodeShaped` gives rows 374 -> 408 (+9.1%, versus +2.4%) and admits `'unchanged.'`,
 * `'means.'` and `'version.'` — sentence fragments that reach `isCodeShaped`'s `.` arm.
 * Those three are pinned as non-anchors in `--self-test` so the collapse goes red.
 */
function isLiteralAnchorShape(lit) {
 return /^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/.test(lit) // snake_case
 || /^[a-z]+(?:[A-Z][A-Za-z0-9]*)+$/.test(lit) // camelCase
 || /^[a-z][a-z0-9]*(?:\.[a-z][A-Za-z0-9]*)+$/.test(lit) // a dotted client path
 || /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/.test(lit); // SCREAMING_SNAKE (#13471)
}

/** Route tails and identifier-shaped string literals appearing on the changed lines. */
function literalAnchorsFromLines(lines, changed) {
 const routes = new Set();
Expand DownExpand Up@@ -1266,9 +1324,7 @@ function literalAnchorsFromLines(lines, changed) {
 for (const m of line.matchAll(/['"]([A-Za-z][\w.$-]{3,63})['"]/g)) {
 const lit = m[1];
 if (GENERIC_ANCHOR_NAMES.has(lit.toLowerCase())) continue;
 // Identifier-shaped only: snake_case, camelCase or dotted. A quoted English word
 // ('ignore', 'utf8') is not a surface anyone documents by that spelling.
 if (!/^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/.test(lit) && !/^[a-z]+(?:[A-Z][A-Za-z0-9]*)+$/.test(lit) && !/^[a-z][a-z0-9]*(?:\.[a-z][A-Za-z0-9]*)+$/.test(lit)) continue;
 if (!isLiteralAnchorShape(lit)) continue;
 literals.add(lit);
 const where = enclosingName();
 noteFrom(from, lit, where ? `a string literal in ${where}` : 'a string literal on a changed line');
Expand DownExpand Up@@ -4348,15 +4404,50 @@ function selfTest() {
 check('PHRASE_ANCHOR_KINDS', 'a rule expression is distinctive by construction', 'rule', true, PHRASE_ANCHOR_KINDS.has('rule'));

 // String literals on a changed line: an identifier-shaped one is surface, English is not.
 const litLines = [" if (rule === 'controlled_by_parent') return maskFieldValue(v);", " fs.readFileSync(p, 'utf8');", " logger.warn('ignore');"];
 const lits = literalAnchorsFromLines(litLines, [1, 2, 3]).literals;
 const litLines = [" if (rule === 'controlled_by_parent') return maskFieldValue(v);", " fs.readFileSync(p, 'utf8');", " logger.warn('ignore');",
 " const ENV = 'OS_TENANCY_POSTURE';", " if (c === 'FLOW_NO_START_NODE') return refuse(c);",
 " // the shape is 'unchanged.' in that arm", " throw new Error('EEXIT');"];
 const lits = literalAnchorsFromLines(litLines, [1, 2, 3, 4, 5, 6, 7]).literals;
 const literalCases = [
 ['controlled_by_parent', true, 'a snake_case literal IS an authoring surface'],
 ['utf8', false, 'an encoding name is not surface'],
 ['ignore', false, 'an English word is not surface'],
 // #13471. The env-var name is the case the whole card was filed on: a page that names
 // env vars and essentially nothing else has no other `literal` route onto an advisory.
 ['OS_TENANCY_POSTURE', true, 'a SCREAMING_SNAKE env-var name IS an authoring surface'],
 ['FLOW_NO_START_NODE', true, 'and so is a refusal code — the measured recall win'],
 // ⛔ The guard rail on the widening, both halves measured on the same 60 commits.
 ['unchanged.', false, 'a quoted sentence fragment is still not surface'],
 ['EEXIT', false, 'a bare all-caps word is not SCREAMING_SNAKE — the shape needs a segment break'],
 ];
 for (const [lit, want, label] of literalCases) check('literalAnchorsFromLines', label, lit, want, lits.has(lit));

 // ── THE PAIR MUST AGREE ON SCREAMING_SNAKE (#13471) ──
 // The defect this closed was not "recall too low", it was TWO PREDICATES CONTRADICTING
 // each other with nothing reporting the split: `isCodeShaped` called `OS_MODE` an
 // identifier (pinned in `shapeCases` above) while `literalAnchorsFromLines` declined to
 // mint any anchor from it. Pin the agreement itself, so neither side can drift back out
 // of step silently — a check on one predicate alone could not have caught this.
 for (const t of ['OS_CLOUD_URL', 'OS_MODE', 'OS_TENANCY_POSTURE', 'ERROR_CODE_LEDGER', 'FLOW_INPUT_SCHEMA_INVALID']) {
 check('isCodeShaped/isLiteralAnchorShape', 'the pair agrees on a SCREAMING_SNAKE token', t,
 true, isCodeShaped(t) === isLiteralAnchorShape(t) && isLiteralAnchorShape(t));
 }

 // ⛔ AND THE DISAGREEMENTS THAT REMAIN ARE DELIBERATE, so the next reader does not
 // "finish the job" by collapsing this test into `isCodeShaped`. The two run over
 // DIFFERENT POPULATIONS — a declaration NAME versus an arbitrary quoted span that may be
 // prose — and delegating measured rows 374 -> 408 (+9.1%, versus +2.4% for the shape
 // above) on the same 60 commits. These three fragments are what it admits.
 const deliberateSplits = [
 ['unchanged.', 'a sentence fragment reaches isCodeShaped through its `.` arm'],
 ['means.', 'ditto — measured, not hypothetical'],
 ['version.', 'ditto'],
 ['IHttpRequest', 'a PascalCase name is already reachable through the `symbol` kind'],
 ];
 for (const [t, label] of deliberateSplits) {
 check('isCodeShaped/isLiteralAnchorShape', label, t, true, isCodeShaped(t) && !isLiteralAnchorShape(t));
 }

 // ── `computedOn` (#9519): the record that names WHICH TREE the answer is about ──
 // Pinned on the pure shaper, so these stay hermetic; the probing wrapper reads real
 // git state by construction. Two properties carry the field's whole value: a merge
Expand Down
Loading