quality: autofix sort-source-methods + cascade canonical script fixes

Picks up the new autofixable sort-source-methods rule from
socket-wheelhouse and the identifier-based _inject-import.js fix
(resolves task #65 / #64). Iterated `oxlint --fix` to convergence;
function declarations re-ordered into private→export alphanumeric
order across the repo. Function declarations are hoisted so the
rewrite is safe at runtime; leading JSDoc / line-comments and
trailing c8-ignore-stop markers travel with each function.

Also re-syncs the canonical scripts/check-paths.mts and
scripts/ai-lint-fix.mts from socket-wheelhouse. The wheelhouse copy
already accounts for state-machine null sentinels (blockKey,
blockKind, inString) and the SKIP_AI_FIX bracket-env access.

Author: jdalton

.config/oxlint-plugin/rules/_inject-import.js

@@ -15,30 +15,52 @@
 /**
  * Walk a Program node body once and figure out:
  *   - the last top-level ImportDeclaration node (or undefined)
- *   - whether `importName` is already imported from `specifier`
+ *   - whether `importName` is already imported (from ANY source)
  *   - whether a top-level `localName` identifier already exists
  *     (any const/let/var or import-as-local with that name)
+ *
+ * Import detection ignores the specifier path: a file inside the lib
+ * package itself imports `getDefaultLogger` from `'../logger'`, while
+ * a downstream repo imports the same name from
+ * `'@socketsecurity/lib/logger'`. Both resolve to the same identifier;
+ * either should count as "already imported" so the autofix doesn't
+ * inject a duplicate (and broken — see issue #64).
+ *
+ * `specifier` is retained in the signature for backward compatibility
+ * but is no longer used for the match decision. Callers may pass any
+ * truthy value (typically the canonical package path the rule would
+ * inject if the import were missing).
  */
-export function summarizeImportTarget(program, specifier, importName, localName) {
+export function summarizeImportTarget(
+  program,
+  // eslint-disable-next-line no-unused-vars
+  specifier,
+  importName,
+  localName,
+) {
   let lastImport
   let hasImport = false
   let hasLocal = false
   for (const stmt of program.body) {
     if (stmt.type === 'ImportDeclaration') {
       lastImport = stmt
-      const source = stmt.source && stmt.source.value
-      if (source === specifier) {
-        for (const spec of stmt.specifiers) {
-          if (
-            spec.type === 'ImportSpecifier' &&
-            spec.imported &&
-            spec.imported.name === importName
-          ) {
-            hasImport = true
-          }
-          if (localName && spec.local && spec.local.name === localName) {
-            hasLocal = true
-          }
+      for (const spec of stmt.specifiers) {
+        if (
+          spec.type === 'ImportSpecifier' &&
+          spec.imported &&
+          spec.imported.name === importName
+        ) {
+          hasImport = true
+        }
+        if (
+          localName &&
+          spec.local &&
+          spec.local.name === localName &&
+          (spec.type === 'ImportSpecifier' ||
+            spec.type === 'ImportDefaultSpecifier' ||
+            spec.type === 'ImportNamespaceSpecifier')
+        ) {
+          hasLocal = true
         }
       }
       continue

.config/oxlint-plugin/rules/sort-source-methods.js

@@ -13,10 +13,15 @@
  * cheap, deterministic, and matches the rest of the fleet's sorting
  * conventions (CLAUDE.md "Sorting" rule).
  *
- * No autofix: re-ordering function declarations is too risky to
- * automate (a `const` that depends on a function declared later via
- * hoisting could break, and TS type narrowing can move with declaration
- * order). Reporting only — caller re-orders manually.
+ * Autofix: emits a single fix that re-orders top-level function
+ * declarations into canonical order. Function declarations are
+ * hoisted, so reordering them is safe for runtime semantics; the
+ * leading JSDoc / line-comment block above each declaration travels
+ * with the function. The rule only autofixes when every function in
+ * the file has a name (anonymous default exports are skipped) and
+ * when there are no top-level non-function statements interleaved
+ * between functions — interleaved statements can carry side-effects
+ * or rely on declaration order, so we don't reshuffle around them.
  */
 
 const SCRIPT_ENTRY_NAMES = new Set(['main'])
@@ -44,6 +49,83 @@ function declVisibility(node) {
   return undefined
 }
 
+/**
+ * Compute the sort key for a function entry. Private functions sort
+ * before exports; within each group, alphanumerical by name. The
+ * script entrypoint (`main`) is pinned to the end regardless of group.
+ */
+function sortKey(entry) {
+  if (entry.isEntrypoint) {
+    // '~' (0x7E) is the highest printable ASCII char, so this sort key
+    // pins the entrypoint to the end of any group.
+    return '~~entrypoint'
+  }
+  return `${entry.visibility === 'private' ? '0' : '1'}${entry.name}`
+}
+
+/**
+ * Locate the byte-range start of a function entry, including any
+ * leading JSDoc / line-comment block that's contiguous with it (a
+ * block separated by a blank line is treated as a free-standing
+ * comment and stays put). Falls back to the node's own start when
+ * there are no leading comments.
+ */
+function leadingCommentStart(sourceCode, node) {
+  const comments = sourceCode.getCommentsBefore
+    ? sourceCode.getCommentsBefore(node)
+    : []
+  if (!comments || comments.length === 0) {
+    return node.range[0]
+  }
+  // Walk from the last comment back, accepting any comment that's
+  // separated from the next one by no more than a single newline
+  // (allows a tight stack of `// foo\n// bar\n/** ... */`).
+  const tokenText = sourceCode.text
+  let earliest = node.range[0]
+  for (let i = comments.length - 1; i >= 0; i--) {
+    const c = comments[i]
+    const between = tokenText.slice(c.range[1], earliest)
+    // Reject if there's a blank line between this comment and the
+    // next block — that means it's a free-standing comment.
+    if (/\n\s*\n/.test(between)) {
+      break
+    }
+    earliest = c.range[0]
+  }
+  return earliest
+}
+
+/**
+ * Locate the byte-range end of a function entry, including any
+ * trailing comment that's contiguous (no blank line between) and
+ * exclusive of the next function. Useful for capturing
+ * c8-ignore-stop markers that pair with a start above the function
+ * — those need to travel with the function when reordered.
+ */
+function trailingCommentEnd(sourceCode, node, nextNodeStart) {
+  const tokenText = sourceCode.text
+  const comments = sourceCode.getCommentsAfter
+    ? sourceCode.getCommentsAfter(node)
+    : []
+  let latest = node.range[1]
+  if (!comments || comments.length === 0) {
+    return latest
+  }
+  for (const c of comments) {
+    if (nextNodeStart !== undefined && c.range[0] >= nextNodeStart) {
+      break
+    }
+    const between = tokenText.slice(latest, c.range[0])
+    // Reject if there's a blank line between this function and the
+    // comment — that means it's a free-standing comment.
+    if (/\n\s*\n/.test(between)) {
+      break
+    }
+    latest = c.range[1]
+  }
+  return latest
+}
+
 /** @type {import('eslint').Rule.RuleModule} */
 const rule = {
   meta: {
@@ -54,6 +136,7 @@ const rule = {
       category: 'Stylistic Issues',
       recommended: true,
     },
+    fixable: 'code',
     messages: {
       groupOutOfOrder:
         'Top-level function `{{name}}` ({{visibility}}) appears after a function from the next visibility group. Order: private functions first (alphanumeric), then exported functions (alphanumeric).',
@@ -64,43 +147,65 @@ const rule = {
   },
 
   create(context) {
+    const sourceCode = context.getSourceCode
+      ? context.getSourceCode()
+      : context.sourceCode
+
     return {
       Program(programNode) {
+        // First pass: collect entries + detect violations.
+        const entries = []
         let lastVisibilityRank = -1
         let lastNameInGroup = null
         let currentVisibility = null
+        const violations = []
 
-        for (const node of programNode.body) {
+        // First find the next program-body node after each function, so
+        // trailingCommentEnd can stop before reaching it.
+        const bodyByIndex = programNode.body
+        for (let i = 0; i < bodyByIndex.length; i++) {
+          const node = bodyByIndex[i]
           const info = declVisibility(node)
           if (!info || !info.fn.id || info.fn.id.type !== 'Identifier') {
             continue
           }
           const name = info.fn.id.name
-          if (SCRIPT_ENTRY_NAMES.has(name)) {
-            // Skip the entrypoint — allowed anywhere.
+          const isEntrypoint = SCRIPT_ENTRY_NAMES.has(name)
+          const start = leadingCommentStart(sourceCode, node)
+          const nextStart =
+            i + 1 < bodyByIndex.length ? bodyByIndex[i + 1].range[0] : undefined
+          const end = trailingCommentEnd(sourceCode, node, nextStart)
+          entries.push({
+            node,
+            name,
+            visibility: info.visibility,
+            isEntrypoint,
+            start,
+            end,
+          })
+
+          if (isEntrypoint) {
             continue
           }
 
           const rank = info.visibility === 'private' ? 0 : 1
 
           if (rank < lastVisibilityRank) {
-            context.report({
+            violations.push({
               node: info.fn.id,
               messageId: 'groupOutOfOrder',
               data: { name, visibility: info.visibility },
             })
             continue
           }
-
           if (rank !== lastVisibilityRank) {
             currentVisibility = info.visibility
             lastVisibilityRank = rank
             lastNameInGroup = name
             continue
           }
-
           if (lastNameInGroup !== null && name < lastNameInGroup) {
-            context.report({
+            violations.push({
               node: info.fn.id,
               messageId: 'alphaOutOfOrder',
               data: {
@@ -113,6 +218,72 @@ const rule = {
             lastNameInGroup = name
           }
         }
+
+        if (violations.length === 0) {
+          return
+        }
+
+        // Build the fix once, applied via the first violation. ESLint
+        // dedupes overlapping fixes, so attaching it once is enough.
+        const sorted = entries.slice().sort((a, b) => {
+          const ka = sortKey(a)
+          const kb = sortKey(b)
+          if (ka < kb) {
+            return -1
+          }
+          if (ka > kb) {
+            return 1
+          }
+          return 0
+        })
+
+        const orderedByPosition = entries
+          .slice()
+          .sort((a, b) => a.start - b.start)
+        const sourceText = sourceCode.text
+        const rangeStart = orderedByPosition[0].start
+        const rangeEnd = orderedByPosition[orderedByPosition.length - 1].end
+
+        // Bail if any non-function, non-comment statements live between
+        // the first and last function — re-ordering would skip over
+        // them and lose their side-effects / declaration-order semantics.
+        for (const stmt of programNode.body) {
+          const isFn = entries.some(e => e.node === stmt)
+          if (isFn) {
+            continue
+          }
+          if (stmt.range[0] >= rangeStart && stmt.range[1] <= rangeEnd) {
+            // Statement is sandwiched between functions; skip autofix.
+            for (const v of violations) {
+              context.report(v)
+            }
+            return
+          }
+        }
+
+        const sortedTexts = sorted.map(e => sourceText.slice(e.start, e.end))
+        const replacement = sortedTexts.join('\n\n')
+
+        // Attach the fix to the first violation only; the rest are
+        // reported without a fix so the user sees what's wrong even
+        // when applying without --fix.
+        let fixerAttached = false
+        for (const v of violations) {
+          if (!fixerAttached) {
+            context.report({
+              ...v,
+              fix(fixer) {
+                return fixer.replaceTextRange(
+                  [rangeStart, rangeEnd],
+                  replacement,
+                )
+              },
+            })
+            fixerAttached = true
+          } else {
+            context.report(v)
+          }
+        }
       },
     }
   },