* chore(#4729): guard the retired-runtime name, and finish the locale residue Phase 5 of 5 on epic #4709, and the phase that closes it. Two parts, one concern: make the tree clean, and keep it clean. The guard is inert until the tree is clean, and shipping the cleanup without the guard is the one-bug-at-a-time pattern this epic exists to end. WHY A GUARD, AND WHY LAST Nothing in CI answered "does any shipped surface still present a retired runtime as live?", and the two gates that look like they should cannot. checkReviewerDocsParity is one-directional: it asserts the PRESENCE of every declared reviewer flag and never the ABSENCE of a retired one, so in #4716 it reported 0 violations while all four locale mirrors still documented --gemini as a live reviewer flag, with usage examples. And tests/gemini-runtime-removed.test.cjs is scoped by construction - its own docblock limits it to the installer CLI contract and the runtime-name-policy exports; it never reads docs/**, gsd-core/workflows/**, commands/** or agents/**. Every extension to it during this epic was a hand-added assertion for a surface somebody had already noticed. A guard written earlier would have red-flagged the very references phases 1b-4b were removing, which is why it lands last. PART A - THE RESIDUE, INCLUDING WORK I SHIPPED INCOMPLETE Each site was judged against its ENGLISH counterpart, not on its own: README.{ja-JP,ko-KR,pt-BR,zh-CN}.md :9 :24 :46 English README.md has ZERO occurrences -> substituted "Antigravity CLI, Kimi CLI" how-to/execute-a-phase.md:88 x4 locales fixed in #4728 -> substitute how-to/verify-and-ship.md:89 x4 locales fixed in #4728 -> substitute FEATURES.md cross-AI CLI list :1419 no Gemini -> DELETE FEATURES.md REQ-MULTI-RT-01 :1709 -> substitute FEATURES.md REQ-SKILLS-03 :1952 -> rewrite FEATURES.md REQ-QUOTA-02 :3256 deleted upstream -> delete VERSIONING.md:133 stale manifest -> see below The twelve README occurrences were an adversarial reviewer's BLOCKER, and the reason they survived my own sweep is structural: root-level *.md was outside the guard's scan set, so the repo's most-read runtime-advertising surface was invisible to the guard meant to police it. :46 is a live installer-runtime claim - it tells the reader the installer will offer a runtime that no longer exists. Checked for the duplicate-name trap before substituting: neither Antigravity nor Kimi appears anywhere in those four files. Two of these are mine to own: I fixed the ENGLISH execute-a-phase.md and verify-and-ship.md in #4728 and left all four mirrors behind. Unfinished work, not a deferral. Two more show why "substitute Gemini -> Antigravity" is the wrong default: in the cross-AI list and REQ-QUOTA-02 English DELETES the name, because Antigravity was already in the list or the classifier had dropped it. Substituting would have duplicated a name - the identical trap ARCHITECTURE.md:24 set in #4728, where English holds Kimi CLI in that slot. VERSIONING.md:133 is a different and worse defect than translation lag. Under "Manifest Version Sync" it listed gemini-extension.json as a version-synced manifest. That file is ABSENT from the repo, and scripts/sync-manifest-versions.cjs says so in its own comment - "#1928: gemini-extension.json was removed with the gemini runtime ... it is no longer a registered manifest" - while VERSIONED_MANIFESTS holds plugin.json, marketplace.json and vscode/package.json. So the doc named a manifest that does not exist AND omitted the one that replaced it. Both fixed, verified against the owning code rather than inferred from the name. The replacement bullet cites #1942, the issue that actually registered vscode/package.json, matching the convention of its neighbours. pt-BR/FEATURES.md is a 77-line stub genuinely lacking two sites, and ko-KR has no REQ-QUOTA-02 line. Skipped and recorded, never invented. PART B - THE GUARD scripts/lint-retired-runtime-name.cjs, modelled on scripts/lint-legacy-dir-name.cjs - the repo's own precedent for this problem shape (forbid a retired token, allowlist frozen content, self-exempt via a split literal, a REPO_ROOT test seam, lib/cli-exit.cjs, exit 0/1). Case sensitivity IS the mechanism, not an accident. The naive guard - "the string gemini must not appear" - is WRONG, not merely noisy: that string is load-bearing across Antigravity's real on-disk contract. A case-sensitive, standalone, capitalised name works because every legitimate reference is spelled differently and therefore cannot match: lowercase config homes (~/.gemini/antigravity, ~/.gemini/config, #3738), lowercase hyphenated model ids (gemini-2.5-flash-lite), uppercase env vars (GEMINI_API_KEY), and GEMINI.md. Table-driven, so the next retired runtime costs one row. THE ALLOWLIST IS THE ENTIRE RISK SURFACE, so it is three tiers, not one. Two rounds of isolated adversarial review reshaped it; both are recorded in .gsd/bug/chore-4729-gemini-drift-guard/60-review.json. ROUND 2 FOUND ONE ROOT CAUSE BEHIND TWO SEPARATE HOLES, and it was mine: both Tier-1 rules treated the ABSENCE of a runtime word as a GRANT. A veto list can never be complete, so "no runtime word found" silently exempted every phrasing nobody had enumerated. Demonstrated: `The installer now offers Gemini 3.`, `Supported agents include Gemini 3, Kimi, and Cursor.` and three more exited 0, as did `Suportamos Gemini, no estilo padrao, como runtime de instalacao.` and `Gemini 兼容，并且是受支持的运行时之一。`, both of which literally contain `runtime` or `运行时`. The fix was to stop enumerating exceptions and invert the evidence direction: Tier 1(a) - the hook DIALECT Antigravity inherits. Position is language-dependent and MEASURED: en Gemini-style/-compatible, ja Gemini スタイル, ko Gemini 스타일/호환, zh Gemini 风格 / 与 Gemini 兼容的, pt "no estilo Gemini" / "compatível com Gemini" where the qualifier PRECEDES the name. The marker must now form an ADJACENT COMPOUND with the name, not merely sit in a +/-24-character window - that window let `| Antigravity | Gemini-style hooks | Gemini support is live |` exit 0, one legitimate reference licensing a fresh live claim 21 characters later. The runtime-word veto is now LINE-GLOBAL. Ten real lines legitimately pair a dialect compound with a runtime word (`~/.gemini/antigravity-cli` in a table cell, "runtime files" in the same sentence); each is an explicit pin rather than a reason to loosen the veto for everyone. Measured: widening it surfaced exactly those ten and no others. Tier 1(b) - the provider/model axis. A version optionally followed by a qualifier, including full-width digits and CJK punctuation, AND positive model-axis evidence on the line, AND no runtime word. The positive requirement is the part that matters: all eight real model-axis lines in the repo name a model explicitly, so requiring it costs nothing on the real tree while flagging every laundering attempt. It is also the honest resolution of the agent/target tension below - rather than guess at an exhaustive veto list, stop treating an empty veto as evidence. Tier 2 - PINNED OCCURRENCES, now SPAN-SCOPED. A pin excuses only a match falling INSIDE an occurrence of its own snippet. Line-level containment let `Known provider menu update: Gemini CLI is once again a selectable GSD runtime.` and `Install target: Google (Gemini) - choose Gemini CLI as your GSD runtime.` both exit 0, because a short snippet elsewhere on the line pre-approved a brand-new claim. Span scoping makes short snippets safe: `Google (Gemini)` can only ever excuse the match inside those 15 characters. A LOAD-TIME validator now requires every pin to contain a retired name, and it immediately caught five of MY OWN pins whose snippets sat BESIDE the name rather than covering it - each would have shipped permanently inert and permanently reported stale. All pins were then reconciled in one pass. A pin is also marked used by PRESENCE on the line now, rather than only on the Tier-2 branch. Previously a pinned line that a general rule also matched never marked its pin used, producing a provably FALSE "no line matches pinned snippet" whose printed remedy told the maintainer to delete a pin that was still needed. Tier 3 - blanket trust, and a new occurrence inside it IS invisible. CHANGELOG.md and `.changeset/` - the rendered changelog and its source, one surface - plus six append-only directories. All 21 `.changeset/` hits were measured to be fragments DESCRIBING the retirement or a fix to it, 464 of them under archived/; a fragment can only describe what already shipped and is deleted at release, so pinning them would be friction with no signal. The cost is stated in the guard's own header rather than hidden. THE SCAN SET IS NOW EVERY TRACKED *.md FILE (1165 read). The original prefix list left `.github/`, `.changeset/`, `capabilities/`, `playbooks/` and `references/` invisible - and `.changeset/*.md` renders into CHANGELOG.md, so a live claim introduced there was invisible at BOTH ends. The escape hatch must now carry a justification (`gsd-allow-retired-runtime-name: <reason>`). A bare marker is rejected: it is checked first, excuses the whole line, and the failure message advertises it, so an unexplained one is indistinguishable from a silenced defect. Plus an anti-vacuity floor counting files actually READ, not files listed - a candidate count stays healthy-looking even if every read failed. A FALSE NEGATIVE I INTRODUCED, AND CLOSED The model-display escape began as a blanket /^ \d/ - "space then a digit" - which also matched "Install for Gemini 2.5 CLI as a supported runtime.", laundering a genuine stale-runtime claim through an attached version number. That was the THIRD appearance of one failure shape in this epic: an exclusion added to suppress false positives creating a false negative. #4716's sweep excluded lines matching gemini-[0-9] to spare Google's model ids, and thereby hid a stale review.models.gemini row whose example value was "gemini-2.5-pro" ON THE SAME LINE. Round 2 then produced the FOURTH and FIFTH instances, which is why the fix this time was to invert the rule's evidence direction rather than to enumerate more exceptions. The veto is word-anchored for Latin terms - unanchored, case-insensitive "CLI" matched inside "client" and would have vetoed legitimate model lists - and raw for CJK terms, where \b is ASCII-word-based and would never fire beside an ideograph, so anchoring them would silently disable the veto in ja/ko/zh. "agent" and "target" were deliberately left OUT: both occur throughout ordinary prose ("AI coding agents (Claude Code, Codex, Gemini 2.5 Pro)"), so vetoing on them would red correct content instead of catching runtime claims. The reasoning is in the guard's comment, not just the omission - and Tier 1(b)'s positive-evidence requirement is what makes that omission safe, since the rule no longer depends on the veto list being complete. COVERAGE tests/lint-retired-runtime-name.test.cjs drives the guard through its GSD_LINT_RETIRED_RUNTIME_REPO_ROOT seam against fixture repos, mirroring tests/lint-legacy-dir-name.test.cjs. A guard never observed failing is not a guard, and this epic already shipped one that was vacuous for 2 of its 5 files, so properties are paired against BOTH failure modes - too broad silently absorbs a future defect, too narrow reds on legitimate content. Floor boundaries are covered at 149/150/151. The round-2 reviewer's sharpest point was about that claim, and it was right: the first matrix's pairing was "true of the properties chosen, not of the predicate's actual surface" - not one of its twenty properties could see the dialect adjacency hole, a non-adjacent runtime word, pin shadowing, or an over-broad pin colliding with a new line. Every one of those is now a committed regression using the reviewer's own attack line verbatim, and the local fixture harness went from 14 cases to 35 (PASS=35 FAIL=0). That harness earned a finding of its own. Its first run reported PASS=2 FAIL=12 with BOTH passes VACUOUS: `git add` has no -q flag on this build, so nothing staged, every fixture hit the empty-walk error path, and the two checks that assert an ABSENCE passed off that error path rather than off real guard logic. A staging failure is now fatal and every absence-asserting check first proves the walk ran and the expected violation was flagged. Later, one case failed because its fixture supplied only one of a pinned file's two approved lines, so the stale-pin check fired correctly - the expectation was wrong, not the guard. Telling those two apart is the whole value of running a matrix rather than reasoning about one. On the two orthogonal reviews: the isolated adversarial pass executed a great deal of code, across two rounds, against its own fixture repos. The security pass did NOT - it self-discloses that it verified by reading only, because node --test is hard-blocked here. Saying so plainly, because "two orthogonal reviews" without that caveat overstates what the second one established. It also raised, and I cleared by measurement, a concern that importing escapeRegex from a gitignored build artifact would break lint:ci on an unbuilt clone: six other tracked scripts already require that exact path, three of them already in lint:ci, and .github/workflows/test.yml:192-193 runs `npm run build:lib` immediately before it for exactly this reason. Part A has no new test deliberately - those edits are covered by the guard itself inside lint:ci, and a separate per-locale assertion would duplicate it and then drift from it. The one exception is the root README case, which IS pinned: that residue was invisible to the guard rather than merely unasserted, so the fix is a scan-set change and needs its own regression test. No mode-bit read-failure fixture was added on purpose: the benches run as root, where chmod-based IO injection is vacuous, so such a test would assert nothing. The test's fixture helpers write throwaway docs/ paths, which trips lint-docs-guard-registration's reader-name heuristic. Resolved the way that lint documents - a header `// docs-guard-exempt:` marker plus a baseline entry - because the fixtures only WRITE scratch data and never read shipped docs; the baseline was re-confirmed, not merely extended, each time locale and adversarial fixtures were added. scripts/lib/macos-conformance-tier.generated.cjs regenerated through its own --write path, since a new test file changes the count lint:generated-sync reads. Fixes #4729 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * chore(#4729): backfill changeset PR number (#4753) --------- Co-authored-by: sim <sim@local> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
612
scripts/lint-retired-runtime-name.cjs
Normal file
612
scripts/lint-retired-runtime-name.cjs
Normal file
@@ -0,0 +1,612 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* lint-retired-runtime-name.cjs
|
||||
*
|
||||
* Prevents a RETIRED GSD runtime name from being presented as if it were a
|
||||
* live runtime (#1928 retired the "Gemini CLI" runtime lane in favor of
|
||||
* Antigravity). Mirrors scripts/lint-legacy-dir-name.cjs's structure and
|
||||
* conventions (same problem shape: forbid a retired token, allowlist
|
||||
* frozen/legitimate content, self-exempt, inline marker, `GSD_LINT_*_REPO_ROOT`
|
||||
* test seam, ./lib/cli-exit.cjs, binary-file skip).
|
||||
*
|
||||
* THE PREDICATE (load-bearing — do not "simplify"):
|
||||
* The forbidden token is matched CASE-SENSITIVELY, standalone (word
|
||||
* boundaries), capitalised: /\bGemini\b/ — NO `i` flag.
|
||||
*
|
||||
* Case sensitivity IS the mechanism. Every LEGITIMATE reference to the
|
||||
* "gemini" string in this repo is spelled differently and therefore cannot
|
||||
* match a case-sensitive `Gemini`:
|
||||
* - Antigravity's config homes are lowercase with a slash:
|
||||
* ~/.gemini/antigravity, ~/.gemini/antigravity-ide, ~/.gemini/config
|
||||
* - Google's model ids are lowercase and hyphenated:
|
||||
* gemini-3.1-pro-preview, gemini-2.5-flash-lite
|
||||
* - env vars are uppercase: GEMINI_CONFIG_DIR, GEMINI_SESSION_ID, GEMINI_API_KEY
|
||||
* - the instruction file is GEMINI.md
|
||||
* A bare capitalised `Gemini` therefore means the retired RUNTIME (or its
|
||||
* retired reviewer lane) is being named as if live — which is the defect
|
||||
* this guard exists to catch.
|
||||
*
|
||||
* RETIRED_RUNTIMES is a table, not a hardcoded single name, so the guard
|
||||
* generalises to the next retired runtime for free. The name is built via
|
||||
* split-string concatenation (same trick the legacy-dir-name precedent
|
||||
* uses) so this guard script cannot flag itself.
|
||||
*
|
||||
* THREE TIERS OF EXEMPTION, deliberately ordered narrowest-first. The
|
||||
* allowlist is the entire risk surface of this guard, so each tier states
|
||||
* what it can and cannot see:
|
||||
*
|
||||
* 1. GENERAL RULES (apply anywhere, no per-file registration) — the two
|
||||
* spellings that are legitimate wherever they appear:
|
||||
* (a) the hook DIALECT Antigravity genuinely inherits: `Gemini-style`,
|
||||
* `Gemini-compatible`, `Gemini スタイル`;
|
||||
* (b) a model-display version on the provider/model axis
|
||||
* (`Gemini 2.5 Pro`), REFUSED when a runtime word also appears on
|
||||
* the line so a version can never launder a runtime claim.
|
||||
* 2. PINNED OCCURRENCES (`ALLOWLIST_OCCURRENCES`) — per-file, per-line
|
||||
* approved snippets. This is what makes a NEW occurrence in an
|
||||
* otherwise-legitimate file FAIL: the file is not blanket-trusted, only
|
||||
* the enumerated lines are. A pin that stops matching is reported as a
|
||||
* stale allowlist entry, so the allowlist cannot silently rot.
|
||||
* 3. FILE / DIR ALLOWLIST — blanket trust, and therefore reserved for
|
||||
* content that is append-only by policy (ADRs, dated research) or
|
||||
* generated-and-locked (CHANGELOG.md). A new occurrence inside these
|
||||
* IS invisible to this guard; that is the accepted cost of not
|
||||
* re-litigating frozen history on every run, and it is why the tier is
|
||||
* kept as small as it is.
|
||||
*
|
||||
* Plus an anti-vacuity floor on files actually READ (not merely listed), so
|
||||
* an empty or failed walk can never report a false clean.
|
||||
*
|
||||
* Exit 0 if no violations; exit 1 if any are found (with stderr diagnostics).
|
||||
*/
|
||||
|
||||
'use strict';
|
||||
|
||||
const { execFileSync } = require('child_process');
|
||||
const fs = require('fs');
|
||||
const path = require('path');
|
||||
const { ExitError, runMain } = require('./lib/cli-exit.cjs');
|
||||
const { escapeRegex } = require('../gsd-core/bin/lib/pattern.cjs');
|
||||
|
||||
// Table of retired runtimes. Each name is constructed via split-string
|
||||
// concatenation so this guard script cannot flag itself when scanned.
|
||||
const RETIRED_RUNTIMES = [
|
||||
{
|
||||
name: 'Gem' + 'ini',
|
||||
retiredBy: '#1928',
|
||||
sunset: '2026-06-18',
|
||||
successor: 'Antigravity',
|
||||
},
|
||||
];
|
||||
|
||||
const RETIRED_RUNTIME_MATCHERS = RETIRED_RUNTIMES.map((r) => ({
|
||||
runtime: r,
|
||||
// Case-sensitive, no 'i' flag — see module header for why.
|
||||
re: new RegExp('\\b' + r.name + '\\b', 'g'),
|
||||
}));
|
||||
|
||||
// Minimum plausible number of files actually READ. An empty or failed walk
|
||||
// must never silently report "clean" (anti-vacuity requirement).
|
||||
const MIN_EXPECTED_FILES = 150;
|
||||
|
||||
const ALLOW_MARKER = 'gsd-allow-retired-runtime-name';
|
||||
// The escape hatch must carry a justification. Bare-marker abuse was raised in
|
||||
// review: the marker is checked first, excuses the whole line, and the failure
|
||||
// message advertises it, so an unexplained one is indistinguishable from a
|
||||
// defect somebody silenced. Require `gsd-allow-retired-runtime-name: <reason>`.
|
||||
const ALLOW_MARKER_RE = new RegExp(escapeRegex(ALLOW_MARKER) + ':\\s*\\S{3,}');
|
||||
const SELF_PATH = path.resolve(__filename);
|
||||
// GSD_LINT_RETIRED_RUNTIME_REPO_ROOT is used by tests to redirect the guard
|
||||
// to a temporary fixture git repo without touching the real working tree.
|
||||
const REPO_ROOT = process.env.GSD_LINT_RETIRED_RUNTIME_REPO_ROOT
|
||||
? path.resolve(process.env.GSD_LINT_RETIRED_RUNTIME_REPO_ROOT)
|
||||
: path.resolve(__dirname, '..');
|
||||
|
||||
// Every tracked *.md file is in scope. An earlier prefix list
|
||||
// (docs/ gsd-core/ commands/ agents/ skills/ + root) left `.changeset/`,
|
||||
// `.github/`, `capabilities/`, `playbooks/` and `references/` invisible —
|
||||
// and `.changeset/*.md` RENDERS INTO CHANGELOG.md, which is blanket-trusted,
|
||||
// so a live claim introduced there was invisible at both ends.
|
||||
|
||||
// TIER 3 — blanket trust. Append-only by policy, or generated-and-locked.
|
||||
// A new occurrence inside these is invisible to this guard; see the module
|
||||
// header for why that cost is accepted here and nowhere else.
|
||||
const ALLOWLIST_FILES = new Set([
|
||||
// Locked by CLAUDE.md ("CHANGELOG.md is Locked") and generated from
|
||||
// changeset fragments: frozen release history, one entry per shipped
|
||||
// release, including the releases that removed the runtime.
|
||||
'CHANGELOG.md',
|
||||
]);
|
||||
|
||||
const ALLOWLIST_DIR_PREFIXES = [
|
||||
// `.changeset/` is CHANGELOG.md before rendering — the same surface, one
|
||||
// step upstream — so it gets the same treatment. Measured: all 21 hits are
|
||||
// fragments DESCRIBING the retirement or a fix to it (e.g. "Retired the
|
||||
// Gemini CLI reviewer lane", "Gemini install output is valid on Windows
|
||||
// PowerShell"), which is what a release note is for. 464 of the 479 live
|
||||
// under `archived/`. Pinning them would add friction with no signal: a
|
||||
// fragment can only describe what already shipped, and it is deleted at
|
||||
// release. The cost is stated rather than hidden — a fragment introducing a
|
||||
// live claim is invisible here, as it is in CHANGELOG.md itself.
|
||||
'.changeset/',
|
||||
// Architecture decision records are append-only history.
|
||||
'docs/adr/',
|
||||
// Frozen historical release notes.
|
||||
'docs/RELEASE-NOTES-LEGACY.md',
|
||||
// Dated research records, incl. the gemini-to-antigravity migration note.
|
||||
'docs/research/',
|
||||
// Dated records.
|
||||
'docs/issueevidence/',
|
||||
'docs/discussions/',
|
||||
'docs/superpowers/',
|
||||
];
|
||||
|
||||
// TIER 2 — pinned occurrences. relPath -> [{ snippet, reason }]. A match is
|
||||
// excused only when its LINE contains one of that file's snippets, so a new,
|
||||
// unrelated occurrence in the same file still fails. Every snippet is a
|
||||
// verbatim fragment of the line it approves.
|
||||
const ALLOWLIST_OCCURRENCES = new Map([
|
||||
['CONTEXT.md', [
|
||||
// The name precedes the annotation on this line, so the snippet must span
|
||||
// both for span containment to cover the match.
|
||||
{ snippet: 'Gemini [runtime removed #1928]', reason: 'session log annotates the removal inline' },
|
||||
]],
|
||||
['GEMINI.md', [
|
||||
{ snippet: 'Gemini CLI was sunset by Google on 2026-06-18', reason: 'states the sunset' },
|
||||
{ snippet: 'shared Gemini 3 backend', reason: 'names the shared model backend Antigravity uses' },
|
||||
]],
|
||||
['docs/whats-new-1.7.0.md', [
|
||||
// Two occurrences on one line, so two pins: span containment deliberately
|
||||
// refuses to let the first excuse the second.
|
||||
{ snippet: 'Gemini CLI removed** (#1928)', reason: 'release note announcing the removal' },
|
||||
{ snippet: 'Google discontinued Gemini CLI on 2026-06-18', reason: 'states the sunset date' },
|
||||
]],
|
||||
['docs/explanation/embeddable-orchestration-system.md', [
|
||||
{ snippet: 'Gemini CLI was retired in', reason: 'records the retirement' },
|
||||
]],
|
||||
// The fragment is the SOURCE; docs/FEATURES.md is generated from it by
|
||||
// scripts/gen-features.cjs, so both carry the same approved line and the
|
||||
// same pin covers each. A marker written into FEATURES.md by hand would be
|
||||
// dropped on the next regeneration.
|
||||
['docs/features/embeddable-orchestration-system-host-integration-interface.md', [
|
||||
{ snippet: 'retired Gemini CLI now redirects to Antigravity CLI', reason: 'records the redirect' },
|
||||
]],
|
||||
['docs/FEATURES.md', [
|
||||
{ snippet: 'retired Gemini CLI now redirects to Antigravity CLI', reason: 'generated from the fragment above' },
|
||||
]],
|
||||
['docs/reference/host-integration-capability-matrix.md', [
|
||||
{ snippet: '(Gemini CLI\'s `thinkingConfig`) was removed as a sunset runtime', reason: 'explains why no config-file member exists' },
|
||||
{ snippet: 'successor to the sunset Gemini CLI per #1928', reason: 'records the sunset and the inherited contract' },
|
||||
]],
|
||||
// --- The inherited hook dialect, where the line ALSO names a runtime -----
|
||||
// Tier 1(a) requires no runtime word on the line, because the tight
|
||||
// "immediately after the name" veto let real laundering through. These ten
|
||||
// lines legitimately pair a dialect compound with a runtime word (usually
|
||||
// `~/.gemini/antigravity-cli` in a table cell, or "runtime files" in the
|
||||
// same sentence), so each is pinned explicitly instead of loosening the
|
||||
// veto for everyone.
|
||||
['docs/ARCHITECTURE.md', [
|
||||
{ snippet: 'Gemini-style `settings.json` hook entries', reason: 'hook dialect Antigravity inherits' },
|
||||
]],
|
||||
['docs/ja-JP/ARCHITECTURE.md', [
|
||||
{ snippet: 'Gemini スタイル `settings.json` フックエントリ', reason: 'hook dialect Antigravity inherits' },
|
||||
]],
|
||||
['docs/ko-KR/ARCHITECTURE.md', [
|
||||
{ snippet: 'Gemini 스타일 `settings.json` 훅 항목', reason: 'hook dialect Antigravity inherits' },
|
||||
]],
|
||||
['docs/pt-BR/ARCHITECTURE.md', [
|
||||
{ snippet: 'no estilo Gemini quando instalado', reason: 'hook dialect Antigravity inherits' },
|
||||
]],
|
||||
['docs/zh-CN/ARCHITECTURE.md', [
|
||||
{ snippet: 'Gemini 风格 `settings.json` hook 条目', reason: 'hook dialect Antigravity inherits' },
|
||||
]],
|
||||
['docs/how-to/install-on-your-runtime.md', [
|
||||
{ snippet: 'Uses Gemini-compatible settings policy', reason: 'settings dialect Antigravity inherits' },
|
||||
]],
|
||||
['docs/ja-JP/how-to/install-on-your-runtime.md', [
|
||||
{ snippet: 'Gemini 互換', reason: 'settings dialect Antigravity inherits' },
|
||||
]],
|
||||
['docs/ko-KR/how-to/install-on-your-runtime.md', [
|
||||
{ snippet: 'Gemini 호환 설정 정책을 사용합니다', reason: 'settings dialect Antigravity inherits' },
|
||||
]],
|
||||
['docs/pt-BR/how-to/install-on-your-runtime.md', [
|
||||
{ snippet: 'compatível com Gemini', reason: 'settings dialect Antigravity inherits' },
|
||||
]],
|
||||
['docs/zh-CN/how-to/install-on-your-runtime.md', [
|
||||
{ snippet: '与 Gemini 兼容的设置策略', reason: 'settings dialect Antigravity inherits' },
|
||||
]],
|
||||
['gsd-core/workflows/reapply-patches.md', [
|
||||
{ snippet: 'pre-#1928 Gemini CLI install', reason: 'legacy-install patch location, explicitly pre-retirement' },
|
||||
]],
|
||||
['gsd-core/workflows/settings-advanced.md', [
|
||||
{ snippet: '(Claude / OpenAI / Gemini / Qwen)', reason: 'model-provider menu, not a GSD runtime' },
|
||||
]],
|
||||
['gsd-core/references/ai-frameworks.md', [
|
||||
{ snippet: 'Google Cloud / Gemini-committed teams', reason: 'provider axis (Google ADK)' },
|
||||
{ snippet: 'Optimized for Gemini; supports other models', reason: 'model axis' },
|
||||
{ snippet: 'teams already committed to Gemini', reason: 'model axis' },
|
||||
{ snippet: 'Model flexibility is required beyond Gemini', reason: 'model axis' },
|
||||
{ snippet: 'Gemini vendor lock-in in practice', reason: 'model axis' },
|
||||
{ snippet: 'Google/Gemini-committed', reason: 'provider axis (Google ADK)' },
|
||||
]],
|
||||
['agents/gsd-framework-selector.md', [
|
||||
// Two occurrences on one line: the menu label and its description.
|
||||
{ snippet: 'Google (Gemini)', reason: 'model-provider choice, not a GSD runtime' },
|
||||
{ snippet: 'Committed to Gemini / Google Cloud / Vertex AI', reason: 'the same menu entry\'s description' },
|
||||
]],
|
||||
['agents/gsd-framework-selector.compact.md', [
|
||||
{ snippet: 'Google (Gemini)', reason: 'model-provider choice, not a GSD runtime' },
|
||||
]],
|
||||
]);
|
||||
|
||||
// Every pin must contain a retired runtime name. Span containment means a
|
||||
// snippet that does not contain the name can never cover a match, so such a
|
||||
// pin is dead config that would also be reported stale forever — fail loud at
|
||||
// load rather than mislead later.
|
||||
for (const [relPath, pins] of ALLOWLIST_OCCURRENCES) {
|
||||
for (const pin of pins) {
|
||||
const names = RETIRED_RUNTIMES.filter((r) => pin.snippet.includes(r.name));
|
||||
if (names.length === 0) {
|
||||
throw new Error(
|
||||
'lint-retired-runtime-name: pin for ' + relPath + ' does not contain a retired '
|
||||
+ 'runtime name and can never match: ' + JSON.stringify(pin.snippet),
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// docs/RELEASE-NOTES-LEGACY.md is a file, not a directory, but the brief
|
||||
// lists it alongside the dir prefixes — treat both files and dirs the same
|
||||
// way via a "startsWith" prefix check.
|
||||
function isAllowlisted(relPath) {
|
||||
if (ALLOWLIST_FILES.has(relPath)) return true;
|
||||
for (const prefix of ALLOWLIST_DIR_PREFIXES) {
|
||||
if (relPath === prefix || relPath.startsWith(prefix)) return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
function isInScanSet(relPath) {
|
||||
return relPath.endsWith('.md');
|
||||
}
|
||||
|
||||
function isBinary(fullPath) {
|
||||
// Read a small chunk and check for NUL bytes.
|
||||
let fd;
|
||||
try {
|
||||
fd = fs.openSync(fullPath, 'r');
|
||||
const buf = Buffer.allocUnsafe(512);
|
||||
const bytesRead = fs.readSync(fd, buf, 0, 512, 0);
|
||||
return buf.subarray(0, bytesRead).includes(0);
|
||||
} catch {
|
||||
return false;
|
||||
} finally {
|
||||
if (fd != null) {
|
||||
try { fs.closeSync(fd); } catch { /* best-effort */ }
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// --- TIER 1(a): the hook dialect Antigravity genuinely inherits -------------
|
||||
// Antigravity reads Gemini-shaped `settings.json` hook entries, and every
|
||||
// locale names that dialect. Marker POSITION is language-dependent and was
|
||||
// measured: en `Gemini-style` / `Gemini-compatible`, ja `Gemini スタイル`,
|
||||
// ko `Gemini 스타일` / `호환`, zh `Gemini 风格` / `与 Gemini 兼容的`, and pt
|
||||
// `no estilo Gemini` / `compatível com Gemini`, where it PRECEDES the name.
|
||||
//
|
||||
// The marker must form an ADJACENT COMPOUND with the name. An earlier version
|
||||
// searched a ±24-character window, which let one legitimate dialect reference
|
||||
// launder a second, unrelated live claim on the same line — a reviewer
|
||||
// demonstrated `| Antigravity | Gemini-style hooks | Gemini support is live |`
|
||||
// exiting 0, because the second occurrence sat 21 characters from `style`.
|
||||
// Adjacency is the property that actually distinguishes a dialect NAME from a
|
||||
// runtime CLAIM, so it is what is tested.
|
||||
const DIALECT_MARKERS = [
|
||||
'style', 'compatible', // en
|
||||
'スタイル', '互換', // ja
|
||||
'스타일', '호환', // ko
|
||||
'风格', '兼容', // zh
|
||||
'estilo', 'compatível', 'compatibilidade', // pt
|
||||
];
|
||||
const DIALECT_ALT = DIALECT_MARKERS.map(escapeRegex).join('|');
|
||||
// Marker immediately follows: "Gemini-style", "Gemini スタイル", "Gemini 兼容".
|
||||
const DIALECT_AFTER_RE = new RegExp('^[-\\s]?(?:' + DIALECT_ALT + ')', 'i');
|
||||
// Marker immediately precedes, optionally through ONE short connective:
|
||||
// "no estilo Gemini", "compatível com Gemini".
|
||||
const DIALECT_BEFORE_RE = new RegExp(
|
||||
'(?:' + DIALECT_ALT + ')\\s*(?:com|with|de|da|do|and)?\\s*$',
|
||||
'i',
|
||||
);
|
||||
|
||||
function isDialectReference(line, matchIndex, afterMatch) {
|
||||
const adjacent = DIALECT_AFTER_RE.test(afterMatch)
|
||||
|| DIALECT_BEFORE_RE.test(line.slice(0, matchIndex));
|
||||
if (!adjacent) return false;
|
||||
// A dialect marker is NOT a licence when the line also asserts a runtime.
|
||||
// This veto is line-global on purpose: the tight "immediately after the
|
||||
// name" form let `Suportamos Gemini, no estilo padrao, como runtime de
|
||||
// instalacao.` and `Gemini 兼容，并且是受支持的运行时之一。` both exit 0 while
|
||||
// literally containing `runtime` / `运行时`. Real lines that legitimately
|
||||
// pair a dialect compound with a runtime word are handled by an explicit
|
||||
// Tier-2 pin, not by loosening this.
|
||||
return !RUNTIME_WORD_RE.test(line);
|
||||
}
|
||||
|
||||
// --- TIER 1(b): the provider/model axis ------------------------------------
|
||||
// Matches the display-name spelling of a model version: a version number
|
||||
// optionally followed by a model qualifier, or one that ends the list item.
|
||||
// Deliberately NOT "space then a digit" — that blanket rule also matched
|
||||
// "Gemini 2.5 CLI as a supported runtime.", laundering a genuine stale-runtime
|
||||
// claim through an attached version number. Full-width digits and CJK
|
||||
// punctuation are included because the translated docs use them.
|
||||
const DIGIT = '0-9\\uFF10-\\uFF19';
|
||||
const SP = ' \\u3000'; // ASCII space + ideographic space
|
||||
const QUALIFIER = 'Pro|Flash|Ultra|Nano|Lite|Preview|Exp|Thinking';
|
||||
const PUNCT = ',;.:)\\]\\u3001\\u3002\\uFF0C\\uFF09\\uFF3D\\uFF1A';
|
||||
const MODEL_DISPLAY_AFTER = new RegExp(
|
||||
'^[' + SP + ']'
|
||||
+ '[' + DIGIT + ']+(?:[.\\uFF0E][' + DIGIT + ']+)*'
|
||||
+ '(?:'
|
||||
+ '[' + SP + ']+(?:' + QUALIFIER + ')\\b[\\w-]*'
|
||||
+ '|[' + SP + ']*[' + PUNCT + ']'
|
||||
+ '|[' + SP + ']*$'
|
||||
+ ')',
|
||||
);
|
||||
|
||||
// Words that indicate a RUNTIME (not a model) is being named on the line, in
|
||||
// every language this repo ships translated docs for. If any appears
|
||||
// alongside a model-display version, the version does NOT get to launder the
|
||||
// runtime claim — the line is still a violation.
|
||||
//
|
||||
// Latin terms are anchored with \b so "CLI" cannot match inside "client" and
|
||||
// "host" cannot match inside "ghost"; CJK terms are matched raw because \b is
|
||||
// ASCII-word-based and would never fire next to a non-word ideograph.
|
||||
//
|
||||
// Deliberately EXCLUDED: "agent" and "target". Both occur throughout ordinary
|
||||
// prose ("AI coding agents (Claude Code, Codex, Gemini 2.5 Pro)"), so vetoing
|
||||
// on them would red legitimate model lists rather than catch runtime claims.
|
||||
const RUNTIME_WORDS = [
|
||||
'CLI',
|
||||
'runtime',
|
||||
'runtimes',
|
||||
'IDE',
|
||||
'extension',
|
||||
'host',
|
||||
'ランタイム', // ja
|
||||
'実行環境', // ja
|
||||
'런타임', // ko
|
||||
'运行时', // zh
|
||||
'运行环境', // zh
|
||||
'tempo de execução', // pt
|
||||
];
|
||||
const RUNTIME_WORD_RE = new RegExp(
|
||||
RUNTIME_WORDS.map((w) => {
|
||||
const esc = escapeRegex(w);
|
||||
// Anchor only when the term begins/ends with an ASCII word character;
|
||||
// \b is meaningless beside an ideograph.
|
||||
return /^[A-Za-z0-9]/.test(w) ? '\\b' + esc + '\\b' : esc;
|
||||
}).join('|'),
|
||||
'i',
|
||||
);
|
||||
|
||||
// Positive evidence that the line is on the MODEL axis. Required, not merely
|
||||
// the absence of a runtime word: a reviewer demonstrated that "absence of a
|
||||
// veto word" is not evidence, with `The installer now offers Gemini 3.`,
|
||||
// `GSD installs cleanly on Gemini 3, Kimi, and Codex.` and
|
||||
// `Supported agents include Gemini 3, Kimi, and Cursor.` all exiting 0 — the
|
||||
// exact laundering class this guard exists to catch. Every real model-axis
|
||||
// line in this repo names a model explicitly, so requiring it costs nothing
|
||||
// and inverts the failure direction from "silently allow" to "flag".
|
||||
const MODEL_WORDS = [
|
||||
'model', 'models', // en
|
||||
'モデル', // ja
|
||||
'모델', // ko
|
||||
'模型', // zh
|
||||
'modelo', 'modelos', // pt
|
||||
];
|
||||
const MODEL_WORD_RE = new RegExp(
|
||||
MODEL_WORDS.map((w) => {
|
||||
const esc = escapeRegex(w);
|
||||
return /^[A-Za-z0-9]/.test(w) ? '\\b' + esc + '\\b' : esc;
|
||||
}).join('|'),
|
||||
'i',
|
||||
);
|
||||
|
||||
/**
|
||||
* Is `pin` satisfied AT this match? The match must fall INSIDE an occurrence
|
||||
* of the pin's snippet, not merely share a line with it.
|
||||
*
|
||||
* Line-level containment was too weak: a reviewer showed
|
||||
* `Known provider menu update: Gemini CLI is once again a selectable GSD
|
||||
* runtime.` and `Install target: Google (Gemini) — choose Gemini CLI as your
|
||||
* GSD runtime.` both exiting 0, because a short snippet elsewhere on the line
|
||||
* pre-approved a brand-new claim. Span containment means a pin can only ever
|
||||
* excuse the occurrence its own text covers.
|
||||
*/
|
||||
function pinCoversMatch(line, matchIndex, matchedText, pin) {
|
||||
const end = matchIndex + matchedText.length;
|
||||
let from = 0;
|
||||
for (;;) {
|
||||
const at = line.indexOf(pin.snippet, from);
|
||||
if (at === -1) return false;
|
||||
if (matchIndex >= at && end <= at + pin.snippet.length) return true;
|
||||
from = at + 1;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Decide whether one MATCH (not the whole line) is legitimate.
|
||||
*
|
||||
* Returns the matched pin, `true` for a general-rule exemption, or `false`
|
||||
* for a violation.
|
||||
*/
|
||||
function classifyMatch(line, matchIndex, matchedText, pins) {
|
||||
// The explicit escape hatch, which must carry a reason.
|
||||
if (ALLOW_MARKER_RE.test(line)) return true;
|
||||
|
||||
const afterMatch = line.slice(matchIndex + matchedText.length);
|
||||
|
||||
// TIER 1(a) — inherited hook dialect, as an adjacent compound.
|
||||
if (isDialectReference(line, matchIndex, afterMatch)) return true;
|
||||
|
||||
// TIER 1(b) — provider/model axis. Needs positive model evidence AND no
|
||||
// runtime word; a version number alone never launders a claim.
|
||||
if (MODEL_DISPLAY_AFTER.test(afterMatch)
|
||||
&& MODEL_WORD_RE.test(line)
|
||||
&& !RUNTIME_WORD_RE.test(line)) {
|
||||
return true;
|
||||
}
|
||||
|
||||
// TIER 2 — a pinned occurrence for this specific file, span-scoped.
|
||||
for (const pin of pins) {
|
||||
if (pinCoversMatch(line, matchIndex, matchedText, pin)) return pin;
|
||||
}
|
||||
|
||||
return false;
|
||||
}
|
||||
|
||||
function main() {
|
||||
// Enumerate tracked files via git ls-files so only committed/staged source is checked.
|
||||
let trackedFiles;
|
||||
try {
|
||||
trackedFiles = execFileSync('git', ['ls-files'], { cwd: REPO_ROOT, encoding: 'utf8' })
|
||||
.split('\n')
|
||||
.map((f) => f.trim())
|
||||
.filter(Boolean);
|
||||
} catch (err) {
|
||||
throw new ExitError(1, 'ERROR lint-retired-runtime-name: git ls-files failed: ' + err.message);
|
||||
}
|
||||
|
||||
const scanFiles = trackedFiles.filter(isInScanSet);
|
||||
|
||||
const violations = [];
|
||||
const usedPins = new Set();
|
||||
// Files present in the scan set, so a stale-pin check can distinguish
|
||||
// "this pin's file is gone/not in this tree" from "this pin matched nothing".
|
||||
const scannedRelPaths = new Set();
|
||||
// Anti-vacuity counts files actually READ, not merely listed: if every read
|
||||
// failed, a candidate count would still look healthy.
|
||||
let filesRead = 0;
|
||||
|
||||
for (const relPath of scanFiles) {
|
||||
if (isAllowlisted(relPath)) continue;
|
||||
|
||||
const fullPath = path.join(REPO_ROOT, relPath);
|
||||
|
||||
// Skip this guard script itself (path-based, though it is not a .md file
|
||||
// and would never be in-scan-set anyway — defense in depth).
|
||||
if (path.resolve(fullPath) === SELF_PATH) continue;
|
||||
|
||||
if (isBinary(fullPath)) continue;
|
||||
|
||||
let content;
|
||||
try {
|
||||
content = fs.readFileSync(fullPath, 'utf8');
|
||||
} catch {
|
||||
// Unreadable files (permissions, etc.) — skip silently.
|
||||
continue;
|
||||
}
|
||||
filesRead += 1;
|
||||
scannedRelPaths.add(relPath);
|
||||
|
||||
const pins = ALLOWLIST_OCCURRENCES.get(relPath) || [];
|
||||
|
||||
const lines = content.split('\n');
|
||||
for (let i = 0; i < lines.length; i++) {
|
||||
const line = lines[i];
|
||||
|
||||
// Mark pins used by PRESENCE on the line, independent of which tier
|
||||
// ultimately excused the match. Previously this was recorded only on
|
||||
// the Tier-2 branch, so a pinned line that a general rule also matched
|
||||
// never marked its pin used and the pin was reported stale — a reviewer
|
||||
// demonstrated a provably false "no line matches pinned snippet" whose
|
||||
// printed remedy told the maintainer to delete a still-needed pin.
|
||||
for (const pin of pins) {
|
||||
if (line.includes(pin.snippet)) usedPins.add(relPath + ' ' + pin.snippet);
|
||||
}
|
||||
|
||||
for (const { runtime, re } of RETIRED_RUNTIME_MATCHERS) {
|
||||
re.lastIndex = 0;
|
||||
let match;
|
||||
while ((match = re.exec(line)) !== null) {
|
||||
const verdict = classifyMatch(line, match.index, match[0], pins);
|
||||
if (verdict) continue;
|
||||
violations.push({
|
||||
file: relPath,
|
||||
line: i + 1,
|
||||
col: match.index + 1,
|
||||
text: line.trim(),
|
||||
runtime,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Anti-vacuity: the scan must have READ a plausible number of files.
|
||||
if (filesRead < MIN_EXPECTED_FILES) {
|
||||
throw new ExitError(
|
||||
1,
|
||||
'ERROR lint-retired-runtime-name: only ' + filesRead + ' file(s) read '
|
||||
+ '(expected at least ' + MIN_EXPECTED_FILES + '); the walk is empty or broken — refusing '
|
||||
+ 'to report a false clean.',
|
||||
);
|
||||
}
|
||||
|
||||
// A pin that no longer matches anything is a stale allowlist entry: the
|
||||
// content it approved was edited or removed, and leaving it in place would
|
||||
// pre-approve a future occurrence nobody reviewed. Only checked for files
|
||||
// actually present in this tree, so fixture roots are unaffected.
|
||||
const stalePins = [];
|
||||
for (const [relPath, pins] of ALLOWLIST_OCCURRENCES) {
|
||||
if (!scannedRelPaths.has(relPath)) continue;
|
||||
for (const pin of pins) {
|
||||
if (!usedPins.has(relPath + ' ' + pin.snippet)) {
|
||||
stalePins.push({ file: relPath, snippet: pin.snippet });
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (violations.length === 0 && stalePins.length === 0) {
|
||||
process.stdout.write(
|
||||
'ok lint-retired-runtime-name: ' + filesRead + ' files scanned, 0 violations\n',
|
||||
);
|
||||
return 0;
|
||||
}
|
||||
|
||||
if (violations.length > 0) {
|
||||
process.stderr.write('\nERROR lint-retired-runtime-name: ' + violations.length + ' violation(s) found\n\n');
|
||||
for (const v of violations) {
|
||||
process.stderr.write(' ' + v.file + ':' + v.line + ': ' + v.text + '\n');
|
||||
}
|
||||
process.stderr.write('\n');
|
||||
for (const runtime of RETIRED_RUNTIMES) {
|
||||
process.stderr.write(
|
||||
'Fix: `' + runtime.name + '` was retired by ' + runtime.retiredBy + ' (sunset ' + runtime.sunset + ') '
|
||||
+ 'in favor of `' + runtime.successor + '`. Either correct the reference to name the live runtime, '
|
||||
+ 'or, if the use is a legitimate historical/provider reference, add the `' + ALLOW_MARKER + '` '
|
||||
+ 'marker on the line.\n',
|
||||
);
|
||||
}
|
||||
process.stderr.write('\n');
|
||||
}
|
||||
|
||||
if (stalePins.length > 0) {
|
||||
process.stderr.write(
|
||||
'ERROR lint-retired-runtime-name: ' + stalePins.length + ' stale allowlist entr'
|
||||
+ (stalePins.length === 1 ? 'y' : 'ies') + ' in ALLOWLIST_OCCURRENCES\n\n',
|
||||
);
|
||||
for (const s of stalePins) {
|
||||
process.stderr.write(' ' + s.file + ': no line matches pinned snippet ' + JSON.stringify(s.snippet) + '\n');
|
||||
}
|
||||
process.stderr.write(
|
||||
'\nFix: the approved line was edited or removed. Delete the pin, or update its '
|
||||
+ 'snippet to the new wording — an unmatched pin pre-approves a future occurrence '
|
||||
+ 'nobody reviewed.\n\n',
|
||||
);
|
||||
}
|
||||
|
||||
return 1;
|
||||
}
|
||||
|
||||
runMain(main);
|
||||
Reference in New Issue
Block a user