chore(sync): cascade inclusive-language rule + scripts fixes

* : same-line
  trailing bypass detection + file-level self-disable
* : file-level inclusive-language disable
* : external-api bypass on git master-branch ref

Author: jdalton

.config/oxlint-plugin/rules/inclusive-language.mts

@@ -1,3 +1,5 @@
+/* oxlint-disable socket/inclusive-language -- this file IS the rule definition; the legacy terms are lookup-table data, not real usage. */
+
 /**
  * @fileoverview Per CLAUDE.md "Inclusive language" rule (full table
  * in docs/references/inclusive-language.md).
@@ -144,6 +146,17 @@ const rule = {
           return true
         }
       }
+      // Fall-back: scan the entire source line containing the node for
+      // a trailing bypass comment. AST-level "after" comments stop at
+      // the statement boundary, but a chained method call's string
+      // literal won't see a trailing comment on the same physical line.
+      const loc = node.loc
+      if (loc && loc.start.line === loc.end.line) {
+        const lineText = sourceCode.lines?.[loc.start.line - 1]
+        if (lineText && BYPASS_RE.test(lineText)) {
+          return true
+        }
+      }
       return false
     }
 

scripts/ai-lint-fix.mts

@@ -52,15 +52,38 @@ const logger = getDefaultLogger()
 // The deterministic linter already handled the unambiguous shapes;
 // what remains is the structural-rewrite set.
 const AI_HANDLED_RULES = new Set([
+  // master/slave — context decides main/primary/controller vs
+  // replica/worker. Other forms (whitelist/blacklist/etc.) auto-fix.
   'socket/inclusive-language',
-  'socket/max-file-lines',
-  'socket/no-fetch-prefer-http-request',
-  'socket/no-placeholders',
+  // Literal username in a user-home path. In source: substitute a
+  // placeholder / env-var / delete. In WASM or generated bundles:
+  // the bundler is leaking the path — fix the build config.
   'socket/personal-path-placeholders',
-  'socket/prefer-async-spawn',
+  // fs.access / fs.stat existence checks. AI rewrites the try/catch
+  // → if/else and preserves metadata calls when the result is
+  // destructured. Wrapper-name shapes (fileExists / pathExists /
+  // isFile / isDir) auto-fix deterministically.
   'socket/prefer-exists-sync',
+  // node:fs default/namespace where references are "weird" (computed
+  // access, passed as a value, reassigned). Plain `fs.X` shapes
+  // auto-fix via scope rename.
   'socket/prefer-node-builtin-imports',
+  // spawnSync where the call site isn't already in async context or
+  // its return value is consumed (assignment, property access).
+  // await/expression-statement shapes auto-fix.
+  'socket/prefer-async-spawn',
+  // null whose surrounding type annotation also mentions null. AI
+  // flips BOTH the annotation and the value in lockstep through the
+  // function signatures / interfaces / return types involved.
+  // Cross-file ripple is handled by per-file passes on the next run.
   'socket/prefer-undefined-over-null',
+  // File splitting needs to choose natural seams.
+  'socket/max-file-lines',
+  // Placeholder finishes need actual implementation.
+  'socket/no-placeholders',
+  // No-fetch needs httpJson/httpText/httpRequest decision based on
+  // how the response is consumed.
+  'socket/no-fetch-prefer-http-request',
 ])
 
 interface OxlintMessage {
@@ -85,7 +108,7 @@ interface CliArgs {
   passthrough: string[]
 }
 
-export function parseArgs(argv: readonly string[]): CliArgs {
+function parseArgs(argv: readonly string[]): CliArgs {
   const passthrough: string[] = []
   let noAi = false
   let staged = false
@@ -110,7 +133,7 @@ export function parseArgs(argv: readonly string[]): CliArgs {
   return { all, noAi, passthrough, staged }
 }
 
-export async function runLintJson(
+async function runLintJson(
   passthrough: readonly string[],
 ): Promise<OxlintFile[]> {
   // Run oxlint directly with --format=json. Bypass `pnpm run lint`
@@ -157,9 +180,7 @@ export async function runLintJson(
   }
 }
 
-export function bucketFindings(
-  files: OxlintFile[],
-): Map<string, OxlintMessage[]> {
+function bucketFindings(files: OxlintFile[]): Map<string, OxlintMessage[]> {
   const byFile = new Map<string, OxlintMessage[]>()
   for (const f of files) {
     const handled = f.messages.filter(
@@ -185,6 +206,7 @@ export function bucketFindings(
 const RULE_GUIDANCE = {
   // oxlint-disable-next-line socket/prefer-undefined-over-null -- null-prototype object literal.
   __proto__: null,
+  // oxlint-disable-next-line socket/inclusive-language -- rule guidance string documents the legacy terms it scans for.
   'socket/inclusive-language':
     'Replace `master`/`slave` with the contextually correct term: `main` (branch), `primary`/`controller` (process), `replica`/`worker`/`secondary`/`follower` (subordinate). Read the surrounding code to pick the right one. Do not autofix when an external API field name forces the legacy term — leave a `// inclusive-language: external-api` comment instead.',
   'socket/personal-path-placeholders':
@@ -205,10 +227,7 @@ const RULE_GUIDANCE = {
     'Replace `fetch(url, opts)` with the right helper from `@socketsecurity/lib/http-request`: `httpJson` when the caller calls `.json()` on the response, `httpText` when it calls `.text()`, `httpRequest` for raw access. Add the named import.',
 } as unknown as Readonly<Record<string, string>>
 
-export function renderFindings(
-  findings: OxlintMessage[],
-  _rel: string,
-): string {
+function renderFindings(findings: OxlintMessage[], _rel: string): string {
   return findings
     .map(
       f =>
@@ -222,7 +241,7 @@ export function renderFindings(
     .join('\n')
 }
 
-export function renderRuleGuidance(findings: OxlintMessage[]): string {
+function renderRuleGuidance(findings: OxlintMessage[]): string {
   const seen = new Set<string>()
   for (const f of findings) {
     if (f.ruleId) {
@@ -260,10 +279,7 @@ export function renderRuleGuidance(findings: OxlintMessage[]): string {
  * the guidance block carries enough context), and how to use Edit /
  * Read. Adding boilerplate dilutes the instructions.
  */
-export function buildPrompt(
-  filePath: string,
-  findings: OxlintMessage[],
-): string {
+function buildPrompt(filePath: string, findings: OxlintMessage[]): string {
   const rel = path.relative(process.cwd(), filePath)
   const findingsBlock = renderFindings(findings, rel)
   const rulesBlock = renderRuleGuidance(findings)
@@ -288,7 +304,7 @@ ${rulesBlock}
 <output>One short sentence summarizing what you changed. No markdown, no code blocks, no preamble.</output>`
 }
 
-export async function runClaudeFix(
+async function runClaudeFix(
   _filePath: string,
   prompt: string,
   cwd: string,
@@ -342,7 +358,7 @@ export async function runClaudeFix(
   return { exitCode, stderr, stdout }
 }
 
-export async function hasClaudeCli(): Promise<boolean> {
+async function hasClaudeCli(): Promise<boolean> {
   try {
     const result = await spawn('claude', ['--version'], {
       shell: process.platform === 'win32',

scripts/lockstep.mts

@@ -139,7 +139,7 @@ type Report =
 // Generic helpers.
 // ---------------------------------------------------------------------------
 
-export function readManifest(manifestPath: string): Manifest {
+function readManifest(manifestPath: string): Manifest {
   if (!existsSync(manifestPath)) {
     logger.error(`lockstep: manifest not found at ${manifestPath}`)
     process.exit(1)
@@ -169,7 +169,7 @@ export function readManifest(manifestPath: string): Manifest {
  * flattened view. Each sub-manifest contributes its rows; the top-level
  * upstreams/sites maps are merged (top-level wins on conflict).
  */
-export function loadManifestTree(rootManifestPath: string): {
+function loadManifestTree(rootManifestPath: string): {
   areas: Array<{ area: string; manifest: Manifest }>
   merged: Manifest
 } {
@@ -223,7 +223,7 @@ export function loadManifestTree(rootManifestPath: string): {
   }
 }
 
-export function gitIn(submoduleDir: string, args: string[]): string {
+function gitIn(submoduleDir: string, args: string[]): string {
   const result = spawnSync('git', ['-C', submoduleDir, ...args], {
     stdio: ['ignore', 'pipe', 'pipe'],
     stdioString: true,
@@ -239,7 +239,7 @@ export function gitIn(submoduleDir: string, args: string[]): string {
   return String(result.stdout)
 }
 
-export function shaIsReachable(submoduleDir: string, sha: string): boolean {
+function shaIsReachable(submoduleDir: string, sha: string): boolean {
   try {
     gitIn(submoduleDir, ['cat-file', '-e', sha])
     return true
@@ -248,7 +248,7 @@ export function shaIsReachable(submoduleDir: string, sha: string): boolean {
   }
 }
 
-export function driftCommitsSince(
+function driftCommitsSince(
   submoduleDir: string,
   sha: string,
   pathInRepo: string,
@@ -280,7 +280,7 @@ export function driftCommitsSince(
   }
 }
 
-export function resolveUpstream(
+function resolveUpstream(
   manifest: Manifest,
   alias: string,
   messages: string[],
@@ -294,7 +294,7 @@ export function resolveUpstream(
   return upstream
 }
 
-export function walkDirFiles(dir: string, extRe: RegExp): string[] {
+function walkDirFiles(dir: string, extRe: RegExp): string[] {
   const files: string[] = []
   if (!existsSync(dir)) {
     return files
@@ -329,7 +329,7 @@ export function walkDirFiles(dir: string, extRe: RegExp): string[] {
   return files
 }
 
-export function countPatternHits(files: string[], patterns: string[]): number {
+function countPatternHits(files: string[], patterns: string[]): number {
   if (patterns.length === 0) {
     return 0
   }
@@ -368,7 +368,7 @@ export function countPatternHits(files: string[], patterns: string[]): number {
 // Kind checkers.
 // ---------------------------------------------------------------------------
 
-export function checkFileFork(
+function checkFileFork(
   row: FileForkRow,
   manifest: Manifest,
   area: string,
@@ -429,7 +429,7 @@ export function checkFileFork(
   return base
 }
 
-export function checkVersionPin(
+function checkVersionPin(
   row: VersionPinRow,
   manifest: Manifest,
   area: string,
@@ -496,6 +496,7 @@ export function checkVersionPin(
     const pref = [
       'refs/remotes/origin/HEAD',
       'refs/remotes/origin/main',
+      // inclusive-language: external-api — git's historical default branch.
       'refs/remotes/origin/master',
     ]
     for (const p of pref) {
@@ -532,7 +533,7 @@ export function checkVersionPin(
   return base
 }
 
-export function checkFeatureParity(
+function checkFeatureParity(
   row: FeatureParityRow,
   _manifest: Manifest,
   area: string,
@@ -620,7 +621,7 @@ export function checkFeatureParity(
   return base
 }
 
-export function checkSpecConformance(
+function checkSpecConformance(
   row: SpecConformanceRow,
   manifest: Manifest,
   area: string,
@@ -659,7 +660,7 @@ export function checkSpecConformance(
   return base
 }
 
-export function checkLangParity(
+function checkLangParity(
   row: LangParityRow,
   manifest: Manifest,
   area: string,
@@ -726,7 +727,7 @@ export function checkLangParity(
  * already covers per-row shape, enum values, id pattern, and required
  * fields — this is the referential-integrity layer on top.
  */
-export function checkCrossRowConsistency(
+function checkCrossRowConsistency(
   rowsWithArea: Array<{ row: Row; area: string }>,
   merged: Manifest,
 ): string[] {
@@ -782,7 +783,7 @@ export function checkCrossRowConsistency(
 // Dispatcher.
 // ---------------------------------------------------------------------------
 
-export function evaluate(
+function evaluate(
   rowsWithArea: Array<{ row: Row; area: string }>,
   merged: Manifest,
 ): Report[] {
@@ -837,7 +838,7 @@ interface AreaSummary {
   error: number
 }
 
-export function summarize(reports: Report[]): AreaSummary[] {
+function summarize(reports: Report[]): AreaSummary[] {
   const byArea = new Map<string, AreaSummary>()
   for (const r of reports) {
     let s = byArea.get(r.area)
@@ -855,7 +856,7 @@ export function summarize(reports: Report[]): AreaSummary[] {
 // Output.
 // ---------------------------------------------------------------------------
 
-export function emitHuman(reports: Report[], summaries: AreaSummary[]): number {
+function emitHuman(reports: Report[], summaries: AreaSummary[]): number {
   logger.info(
     `lockstep — ${reports.length} row(s) across ${summaries.length} area(s)`,
   )