@skyramp/mcp 0.4.2 → 0.4.3-rc.2

package/build/utils/utils-verify/importers.js

@@ -1,5 +1,8 @@
 import * as path from "path";
 import { generatedSiblings } from "./call-sites.js";
+import { realpath } from "./locate.js";
+import { blankComments, blankCommentsAndStrings, } from "./parse.js";
+import { stringSpans } from "../pom-scope/strip.js";
 /** The strings a sibling's source would contain if it imports the module at
  *  `modulePath` (relative to the sibling's directory): the path form for TS/JS
  *  specifiers, and the dotted Python form — `../shared/X` → `..shared.X`,
@@ -13,29 +16,36 @@ export function moduleMentionCandidates(modulePath) {
     return [posix, "./" + posix, rest, dotted, "." + rest];
 }
 /**
- * Count, per utils helper, how many Skyramp-generated tests in the spec's directory
- * import it — the spec under verification included.
+ * The Skyramp-generated tests in the spec's directory that import each utils helper —
+ * the spec under verification included. THE importer walk: the single-importer
+ * advisory and the changed-helper caller set both read it, so one definition decides
+ * what counts as an importing test.
  *
- * Findings:
- * - 0 importers: nothing imports the helper, not even the spec that wrote it — a
- *   dead helper, actionable on any run.
- * - 1 importer: not (yet) shared. Reported only when the directory holds at least
- *   TWO delivered tests: on a first run every helper has exactly one importer by
- *   construction (it seeds the utils file), so listing them would be guaranteed
- *   noise on the most common path.
- * Fails open to "no findings" on any read error.
+ * Fails open to an unread scan on any error. That is a silence, not an empty answer;
+ * `read` is what tells the two apart.
+ *
+ * SCOPE, which every caller inherits: siblings are the spec's OWN DIRECTORY. A
+ * generated test importing the module from another directory is not found here, so
+ * the importer list is a LOWER BOUND on the callers, never the complete set.
  */
-export async function singleImporterHelpers(testFile, utilsFiles, helpersByFile, spec, preReadSiblings) {
+export async function helperImporters(testFile, utilsFiles, helpersByFile, spec, preReadSiblings) {
     let dir;
     let siblings;
     try {
-        dir = path.dirname(testFile);
+        // CANONICAL, because the module paths this is compared against are: they come
+        // from locateUtilsFiles, which realpaths everything. A spec named through a
+        // symlinked parent (macOS `/var` → `/private/var`, and every worktree under a
+        // linked temporary directory) otherwise relativises to a `../../…` path no
+        // sibling's import can contain, so every helper in the module read as imported
+        // by nothing — silently, since an empty importer list is also the honest answer
+        // for a helper nobody calls.
+        dir = path.dirname(await realpath(testFile));
         siblings =
             preReadSiblings ??
                 (await generatedSiblings(testFile, spec, { includeSelf: true }));
     }
     catch {
-        return [];
+        return { helpers: [], siblings: [], read: false };
     }
     // `importedNames` matches by basename stem, so a bare `from SkyrampUtils import …`
     // in a sibling would also be credited to `../shared/SkyrampUtils`. A sibling's
@@ -49,30 +59,110 @@ export async function singleImporterHelpers(testFile, utilsFiles, helpersByFile,
         inDir: path.dirname(f) === dir,
         mentions: moduleMentionCandidates(path.relative(dir, f).replace(/\.[^.]+$/, "")),
     }));
-    // helper key = `${utilsFile}\0${name}` → number of importing tests
-    const counts = new Map();
+    // helper key = `${utilsFile}\0${name}` → the tests importing it
+    const importers = new Map();
     for (const [file, helpers] of helpersByFile)
         for (const h of helpers)
-            counts.set(`${file}\0${h.name}`, 0);
-    for (const { content } of siblings) {
+            importers.set(`${file}\0${h.name}`, []);
+    for (const { file: sibling, content } of siblings.files) {
+        // Imports are read from the CODE, never from prose. A docstring or a comment
+        // quoting `from SkyrampUtils import …` would otherwise make that test a caller of
+        // a helper it cannot reach, and the gate would refuse the report over it — a
+        // false block, which this design treats as the worst outcome available to it.
+        const code = importScanSource(content, spec);
         for (const { file: utilsFile, stem, inDir, mentions } of stems) {
             if (!inDir && !mentions.some((c) => content.includes(c)))
                 continue;
-            const imported = new Set(spec.importedNames(content, stem));
+            const imported = new Set(spec.importedNames(code, stem));
             for (const h of helpersByFile.get(utilsFile) ?? [])
-                if (imported.has(h.name)) {
-                    const k = `${utilsFile}\0${h.name}`;
-                    counts.set(k, (counts.get(k) ?? 0) + 1);
-                }
+                if (imported.has(h.name))
+                    importers.get(`${utilsFile}\0${h.name}`)?.push(sibling);
         }
     }
-    const secondRunExists = siblings.length >= 2;
-    const out = [];
-    for (const [file, helpers] of helpersByFile)
-        for (const h of helpers) {
-            const n = counts.get(`${file}\0${h.name}`) ?? 0;
-            if (n === 0 || (n === 1 && secondRunExists))
-                out.push({ file, helper: h.name, line: h.line, importers: n });
-        }
-    return out;
+    const helpers = [];
+    for (const [file, hs] of helpersByFile)
+        for (const h of hs)
+            helpers.push({
+                file,
+                helper: h.name,
+                line: h.line,
+                importers: importers.get(`${file}\0${h.name}`) ?? [],
+            });
+    return {
+        helpers,
+        siblings: siblings.files.map((s) => s.file),
+        read: siblings.complete,
+    };
+}
+/**
+ * Helpers with 0 or 1 importing test — the advisory slice of {@link helperImporters}.
+ *
+ * Findings:
+ * - 0 importers: nothing imports the helper, not even the spec that wrote it — a
+ *   dead helper, actionable on any run.
+ * - 1 importer: not (yet) shared. Reported only when the directory holds at least
+ *   TWO delivered tests: on a first run every helper has exactly one importer by
+ *   construction (it seeds the utils file), so listing them would be guaranteed
+ *   noise on the most common path.
+ *
+ * Reports NOTHING from an incomplete walk. This is a claim, not a gate — it tells the
+ * agent a helper is dead and to call it or delete it — and a walk that could not read
+ * every candidate cannot support it: the file it failed to read may be the importer.
+ * Silence on doubt, so the finding stays trustworthy when it is made.
+ */
+export async function singleImporterHelpers(testFile, utilsFiles, helpersByFile, spec, preReadSiblings) {
+    const scan = await helperImporters(testFile, utilsFiles, helpersByFile, spec, preReadSiblings);
+    if (!scan.read)
+        return [];
+    const secondRunExists = scan.siblings.length >= 2;
+    return scan.helpers.filter((h) => h.importers.length === 0 || (h.importers.length === 1 && secondRunExists));
+}
+/**
+ * `content` prepared for an import scan: the copy `importedNames` should read.
+ *
+ * Comments go in both languages — an import quoted in prose is not an import, and
+ * counting one makes a test a "caller" of a helper it cannot reach, which a gate then
+ * blocks on. Python string CONTENTS go too, since a Python import names no string, so
+ * the usage example in a docstring stops counting.
+ *
+ * TS/JS cannot blank every string, because the module specifier IS a string
+ * (`from "./skyrampUtils"`). Only the specifiers are kept: a string that directly
+ * follows `from` or `require(` stays, and every other string is blanked. Requiring
+ * the import to start a line is not enough on its own — a template literal holds
+ * whole lines, and the `require` form is bounded by a declaration keyword rather than
+ * by the line start — so quoted code kept reading as executable code.
+ */
+export function importScanSource(content, spec) {
+    if (spec.language === "python")
+        return blankCommentsAndStrings(content, spec);
+    const noComments = blankComments(content, spec);
+    const out = noComments.split("");
+    for (const { start, end } of stringSpans(noComments)) {
+        // A module specifier is a string in exactly one position: straight after `from`
+        // or after `require(`. Anything else is data, whatever it spells.
+        if (isSpecifierPosition(noComments, start))
+            continue;
+        for (let i = start; i < end; i++)
+            out[i] = noComments[i] === "\n" ? "\n" : " ";
+    }
+    return out.join("");
+}
+/** Whether the string opening at `at` sits where a module specifier does: after
+ *  `from`, or after `require(`, with only whitespace between. Read backwards over a
+ *  fixed window rather than by matching a regex against `src.slice(0, at)` — that
+ *  copied the file once per literal, quadratic in a spec with thousands of them. */
+function isSpecifierPosition(src, at) {
+    let i = at;
+    while (i > 0 && /\s/.test(src[i - 1]))
+        i--;
+    const word = (w) => src.slice(Math.max(0, i - w.length), i) === w &&
+        !/[\w$]/.test(src[i - w.length - 1] ?? "");
+    if (word("from"))
+        return true;
+    if (src[i - 1] !== "(")
+        return false;
+    i--;
+    while (i > 0 && /\s/.test(src[i - 1]))
+        i--;
+    return word("require");
 }

package/build/utils/utils-verify/in-house.js

@@ -1,14 +1,12 @@
-import { execFile } from "child_process";
-import { promisify } from "util";
 import * as fs from "fs";
 import * as path from "path";
 import { detectGitRoot } from "../gitStaging.js";
 import { logger } from "../logger.js";
 import { escapeRegExp } from "../regex.js";
-import { importedModules, realpath, UTILS_FILE_HEADER_RE } from "./locate.js";
+import { hasUtilsHeaderContent, importedModules, realpath } from "./locate.js";
+import { contentAtHead } from "./head.js";
 import { blankComments, blankCommentsAndStrings, defaultAt, hasDefault, parseUtilsFile, } from "./parse.js";
 import { blankStringContents, matchingClose } from "./action-key.js";
-const execFileAsync = promisify(execFile);
 export async function locateInHouseModules(params) {
     const root = params.cwd ?? detectGitRoot(params.testFile);
     if (!root)
@@ -26,7 +24,7 @@ export async function locateInHouseModules(params) {
         const rel = path.relative(realRoot, real);
         if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel))
             continue;
-        const head = await headContent(realRoot, rel.split(path.sep).join("/"));
+        const head = await contentAtHead(real, realRoot);
         if (head === undefined)
             continue; // not tracked: created this run, or never a file
         // Ownership is read at HEAD and nowhere else. A Skyramp module from an earlier
@@ -34,31 +32,12 @@ export async function locateInHouseModules(params) {
         // did to its first lines; a module headerless at HEAD is the customer's, and a
         // header the working copy gained since is a change the additive gate refuses —
         // reading the working copy here would let that stamp reclassify their file.
-        if (hasHeader(head))
+        if (hasUtilsHeaderContent(head))
             continue;
         out.push({ file: real, relPath: rel.split(path.sep).join("/") });
     }
     return out.sort((a, b) => a.file.localeCompare(b.file));
 }
-/** Whether a module's first lines carry the Skyramp utils header. */
-function hasHeader(content) {
-    return UTILS_FILE_HEADER_RE.test(content.split("\n").slice(0, 5).join("\n"));
-}
-/** The module's content at HEAD, or `undefined` when HEAD does not hold it (or git
- *  cannot be asked). */
-async function headContent(root, rel) {
-    try {
-        const { stdout } = await execFileAsync("git", ["show", `HEAD:${rel}`], {
-            cwd: root,
-            encoding: "utf8",
-            maxBuffer: 16 * 1024 * 1024,
-        });
-        return stdout;
-    }
-    catch {
-        return undefined;
-    }
-}
 /** The number of arguments a helper accepts: from the position of its last required
  *  parameter to its total, a rest parameter opening the top. A parameter with a
  *  default, an optional `x?`, or a Python `*args`/`**kw` is not required — but a
@@ -224,20 +203,36 @@ function definitionLineOf(moduleLines, name) {
     const re = new RegExp(`\\b(?:class|const|let|var|enum|interface|type|function|def)\\s+${escapeRegExp(name)}\\b`);
     return moduleLines.find((l) => re.test(l));
 }
-/** `export { name } from "…"`, or `export * from "…"` — a binding of another module
- *  exported here. Exists as an export; not readable as a helper of this module. */
+/** `export { name } from "…"`, `export * from "…"`, or a binding this module IMPORTS
+ *  and then lists in a local `export { … }` — a binding of another module exported
+ *  here. Exists as an export; not readable as a helper of this module. The last form
+ *  is how a fixtures module passes Playwright's `expect` through beside its extended
+ *  `test`: `import { test as base, expect } from "@playwright/test"; … export { expect };`. */
 function isReExported(moduleCode, name) {
     // `export * from "./x"` may legally provide any name; nothing here can read it.
     if (/\bexport\s*\*\s*from\b/.test(moduleCode))
         return true;
-    for (const m of moduleCode.matchAll(/\bexport\s*\{([^}]*)\}\s*from\b/g))
+    for (const m of moduleCode.matchAll(/\bexport\s*\{([^}]*)\}(\s*from\b)?/g))
         for (const raw of m[1].split(",")) {
             const [local, exported] = raw.trim().split(/\s+as\s+/);
-            if ((exported ?? local) === name)
+            if ((exported ?? local) !== name)
+                continue;
+            // `export { x } from "…"` names the other module's binding directly; a local
+            // list exports this module's binding, which is another module's only when
+            // an import brought it in.
+            if (m[2] || isImportedBinding(moduleCode, local))
                 return true;
         }
     return false;
 }
+/** Whether an import statement or a CommonJS destructure binds `local` in this
+ *  module: `import { local }`, `import { x as local }`, `import local from`,
+ *  `import * as local from`, `const { local } = require(…)`. */
+function isImportedBinding(moduleCode, local) {
+    const n = escapeRegExp(local);
+    return (new RegExp(`\\bimport\\s+(?:type\\s+)?[^;]*?(?:[{,]\\s*(?:\\w+\\s+as\\s+)?${n}\\s*[,}]|\\*\\s+as\\s+${n}\\b|\\b${n}\\s*(?:,|\\bfrom\\b))[^;]*?\\bfrom\\b`).test(moduleCode) ||
+        new RegExp(`\\b(?:const|let|var)\\s*\\{[^}]*\\b${n}\\b[^}]*\\}\\s*=\\s*require\\s*\\(`).test(moduleCode));
+}
 function importLine(lines, name) {
     const re = new RegExp(`\\b${escapeRegExp(name)}\\b`);
     const i = lines.findIndex((l) => /\b(?:import|require|from)\b/.test(l) && re.test(l));
@@ -306,7 +301,7 @@ export async function additiveChanges(file, root, spec) {
         duplicates: [],
     };
     const rel = path.relative(root, file).split(path.sep).join("/");
-    const head = await headContent(root, rel);
+    const head = await contentAtHead(file, root);
     if (head === undefined) {
         logger.warning("Could not read an in-house module at HEAD — the additive gate did not run", { file });
         return result;
@@ -335,7 +330,7 @@ export async function additiveChanges(file, root, spec) {
     }
     result.ran = true;
     // Rule 5 of the design, enforced: the file stays the customer's file.
-    if (hasHeader(work) && !hasHeader(head))
+    if (hasUtilsHeaderContent(work) && !hasUtilsHeaderContent(head))
         result.violations.push({
             kind: "in-house-modified",
             file,

package/build/utils/utils-verify/index.d.ts

@@ -2,9 +2,12 @@ export * from "./language-spec.js";
 export * from "./parse.js";
 export * from "./allow.js";
 export * from "./locate.js";
+export * from "./head.js";
 export * from "./verify.js";
 export * from "./stage.js";
 export * from "./call-sites.js";
+export * from "./importers.js";
+export * from "./changed-helpers.js";
 export * from "./action-sites.js";
 export * from "./retrofit-equivalence.js";
 export * from "./in-house.js";

package/build/utils/utils-verify/index.js

@@ -2,9 +2,12 @@ export * from "./language-spec.js";
 export * from "./parse.js";
 export * from "./allow.js";
 export * from "./locate.js";
+export * from "./head.js";
 export * from "./verify.js";
 export * from "./stage.js";
 export * from "./call-sites.js";
+export * from "./importers.js";
+export * from "./changed-helpers.js";
 export * from "./action-sites.js";
 export * from "./retrofit-equivalence.js";
 export * from "./in-house.js";

package/build/utils/utils-verify/language-spec.js

@@ -115,7 +115,10 @@ function tsModuleQualifiers(spec, stem) {
     const stemRe = stem.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     const from = `["'][^"']*\\/${stemRe}(?:\\.[cm]?[jt]s)?["']`;
     const out = new Set();
-    for (const m of spec.matchAll(new RegExp(`import\\s*\\*\\s*as\\s+([A-Za-z_$][\\w$]*)\\s*from\\s*${from}`, "g")))
+    // Anchored to the START of a line, for the same reason the named-import scan is: a
+    // TypeScript specifier is itself a string, so the scan cannot blank strings to keep
+    // prose out — it has to require the import to BE a statement.
+    for (const m of spec.matchAll(new RegExp(`^\\s*import\\s*\\*\\s*as\\s+([A-Za-z_$][\\w$]*)\\s*from\\s*${from}`, "gm")))
         out.add(m[1]);
     for (const m of spec.matchAll(new RegExp(`(?:const|let|var)\\s+([A-Za-z_$][\\w$]*)\\s*=\\s*require\\(\\s*${from}\\s*\\)`, "g")))
         out.add(m[1]);
@@ -125,7 +128,12 @@ function tsImportedNames(spec, stem) {
     const names = new Set();
     const stemRe = stem.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     const from = `["'][^"']*\\/${stemRe}(?:\\.[cm]?[jt]s)?["']`;
-    for (const m of spec.matchAll(new RegExp(`import\\s*\\{([^}]*)\\}\\s*from\\s*${from}`, "g"))) {
+    // Anchored to the START of a line: a TypeScript specifier is itself a string, so
+    // the scan cannot blank strings to keep prose out — it has to require the import to
+    // BE a statement. Without this, ordinary data (`const sample = 'import { x } from
+    // "./skyrampUtils"'`) counted as an import, and a gate reading importers as callers
+    // would block a report over a test that cannot reach the helper.
+    for (const m of spec.matchAll(new RegExp(`^\\s*import\\s*\\{([^}]*)\\}\\s*from\\s*${from}`, "gm"))) {
         for (const raw of m[1].split(",")) {
             // The EXPORTED name (before `as`): the count checks what the utils file defines,
             // so an alias would under-count. Same choice as the Python `from … import x as y`.

package/build/utils/utils-verify/locate.d.ts

@@ -3,6 +3,9 @@ import { type UtilsLanguageSpec } from "./language-spec.js";
  *  <timestamp>`. Deliberately NOT the bare `SKYRAMP_UTILS_HEADER`, which every generated
  *  TEST also carries as its codegen marker (`Generated by Skyramp v<version>`). */
 export declare const UTILS_FILE_HEADER_RE: RegExp;
+/** Whether `content`'s first lines carry the utils header — the test that makes a
+ *  file Skyramp's shared module, for a caller that already holds the content. */
+export declare function hasUtilsHeaderContent(content: string): boolean;
 export interface LocateUtilsParams {
     /** Absolute path of the delivered test file. */
     testFile: string;

package/build/utils/utils-verify/locate.js

@@ -15,6 +15,11 @@ export const UTILS_FILE_HEADER_RE = new RegExp(`${SKYRAMP_UTILS_HEADER.replace(/
 const HEADER_SCAN_LINES = 5;
 /** Enough bytes for five header lines; a utils file is never read whole to find them. */
 const HEADER_SCAN_BYTES = 2048;
+/** Whether `content`'s first lines carry the utils header — the test that makes a
+ *  file Skyramp's shared module, for a caller that already holds the content. */
+export function hasUtilsHeaderContent(content) {
+    return UTILS_FILE_HEADER_RE.test(content.split("\n").slice(0, HEADER_SCAN_LINES).join("\n"));
+}
 /**
  * Every shared utils file relevant to `testFile`, by CONTENT, never by name.
  *
@@ -130,12 +135,7 @@ export async function hasUtilsHeader(file) {
         fh = await fs.promises.open(file, "r");
         const buf = Buffer.alloc(HEADER_SCAN_BYTES);
         const { bytesRead } = await fh.read(buf, 0, HEADER_SCAN_BYTES, 0);
-        const head = buf
-            .toString("utf8", 0, bytesRead)
-            .split("\n")
-            .slice(0, HEADER_SCAN_LINES)
-            .join("\n");
-        return UTILS_FILE_HEADER_RE.test(head);
+        return hasUtilsHeaderContent(buf.toString("utf8", 0, bytesRead));
     }
     catch (err) {
         // A missing file is the common, silent case. Anything else means a file exists

package/build/utils/utils-verify/parse.d.ts

@@ -1,13 +1,21 @@
 import { type UtilsLanguageSpec } from "./language-spec.js";
 import { type HelperSleep } from "./fixed-sleep.js";
+import { type SourceSpan } from "../pom-scope/strip.js";
 export interface HelperAssertion {
     line: number;
     text: string;
 }
 export interface UtilsHelper {
     name: string;
-    /** 1-based line of the definition. */
+    /** 1-based line of the definition — the `def`/`function` line, which is where a
+     *  finding is reported. */
     line: number;
+    /** 1-based line where the definition's SOURCE begins: the first line of its
+     *  decorator stack, or `line` when it has none. A decorator is part of what the
+     *  helper does — `@retry(3)` against `@retry(1)` changes every call site — so a
+     *  reader comparing implementations has to start here, while a reader pointing at
+     *  the helper still uses `line`. */
+    startLine: number;
     /** 1-based line of the last body line (inclusive). */
     endLine: number;
     method?: string;
@@ -104,6 +112,10 @@ export declare function parseUtilsFile(content: string, spec: UtilsLanguageSpec)
 /** True when the `path` value is a single string literal ending the argument — a
  *  concatenation (`"/api/orders/" + str(id) + "/items"`) has no route this can name. */
 export declare function isSingleLiteral(line: string, m: RegExpExecArray): boolean;
+/** The string literals in `src`, quotes included, in order. TS/JS go through the
+ *  shared scanner; Python goes through the one below, so a caller sees one definition
+ *  of a literal for each language. */
+export declare function stringSpansOf(src: string, spec: UtilsLanguageSpec): SourceSpan[];
 /** Comments and string CONTENTS blanked (quotes kept, line count preserved). Python
  *  comments are `#…`; TS/JS go through the shared stripper. */
 /** String CONTENTS blanked (quotes kept, comments kept, line count preserved). */

package/build/utils/utils-verify/parse.js

@@ -7,7 +7,7 @@ function actionSequence(body, language) {
     return keys ? { actionKey: keys.join("; "), actionSteps: keys } : {};
 }
 import { fixedSleepsIn, pythonSleepBindings, } from "./fixed-sleep.js";
-import { stripComments, stripCommentsAndStrings, stripStrings, } from "../pom-scope/strip.js";
+import { stringSpans, stripComments, stripCommentsAndStrings, stripStrings, } from "../pom-scope/strip.js";
 /** Whether the `<` at `i` opens a generic (`Record<string, …>`, `Array<{…}>`) rather
  *  than comparing (`i < 3`): a generic follows an identifier or `>` and is followed
  *  by a type start; a comparison is followed by a number, a space and a value, or
@@ -266,6 +266,7 @@ export function parseUtilsFile(content, spec) {
         const helper = {
             name,
             line: start + 1,
+            startLine: decoratorStart(lines, structure, start) + 1,
             endLine: Math.max(end, start + 1),
             wrapsRequest: false,
             hasGuard: hasPageErrorGuard(body.join("\n"), spec),
@@ -355,69 +356,100 @@ export function isSingleLiteral(line, m) {
         after.startsWith(")") ||
         after.startsWith("}"));
 }
-/** Comments and string CONTENTS blanked (quotes kept, line count preserved). Python
- *  comments are `#…`; TS/JS go through the shared stripper. */
-/** String CONTENTS blanked (quotes kept, comments kept, line count preserved). */
-export function blankStrings(src, spec) {
-    if (spec.language !== "python")
-        return stripStrings(src);
-    return blankPythonStrings(src);
+/** The string literals in `src`, quotes included, in order. TS/JS go through the
+ *  shared scanner; Python goes through the one below, so a caller sees one definition
+ *  of a literal for each language. */
+export function stringSpansOf(src, spec) {
+    return spec.language === "python" ? pythonStringSpans(src) : stringSpans(src);
 }
 /**
- * Blank every Python string literal, triple-quoted ones included, preserving offsets.
+ * The string literals in Python source, quotes included.
  *
- * A line-by-line regex cannot do this: a `"""…"""` block spans lines, so a `#` inside a
- * docstring or an embedded SQL block read as a comment. Every scanner built on this
- * then treated quoted text as code the file executes — and the delivery-time marker
- * strip deleted a line out of a value rather than out of a comment.
+ * Triple quotes are tested BEFORE single ones, and this is the whole reason the scan
+ * is not a regex: a `"""` read one quote at a time matches an empty `""` and leaves
+ * the payload to be treated as code. A multiline payload's own indentation is then
+ * read as formatting, and a change to it disappears.
+ *
+ * A single-quoted string that never closes before the end of its line is a stray
+ * apostrophe in code (`# don't`, or a regex), not an opener — the same rule the TS
+ * scanner applies. A prefix (`r`, `f`, `b`, `rb`) is code; only the quote opens the
+ * literal.
+ *
+ * COMMENTS ARE SKIPPED while looking for an opener, in the same pass rather than a
+ * prior one: a comment that merely mentions a quote (`# a docstring starts with """`)
+ * would otherwise open a span that runs to the next real delimiter, blanking every
+ * definition in between so its helpers vanish from every check that reads the
+ * structure. A `#` inside a literal is not a comment, which is why one pass has to
+ * decide both.
  */
-function blankPythonStrings(src) {
-    const out = src.split("");
-    const blank = (from, to) => {
-        for (let k = from; k < to; k++)
-            if (out[k] !== "\n")
-                out[k] = " ";
-    };
-    let i = 0;
-    const n = src.length;
-    while (i < n) {
-        const c = src[i];
-        // A comment runs to the end of the line and holds no string opener.
-        if (c === "#") {
-            while (i < n && src[i] !== "\n")
+function pythonStringSpans(src) {
+    const out = [];
+    for (let i = 0; i < src.length; i++) {
+        const q = src[i];
+        if (q === "#") {
+            // Outside a literal by construction — a literal advances `i` past its end.
+            while (i < src.length && src[i] !== "\n")
                 i++;
             continue;
         }
-        if (c !== '"' && c !== "'") {
-            i++;
+        if (q !== '"' && q !== "'")
             continue;
-        }
-        // A string prefix (r, b, f, u, rb, …) is part of the literal, not of the quote.
-        const triple = src.startsWith(c.repeat(3), i);
-        const quote = triple ? c.repeat(3) : c;
-        const start = i;
-        i += quote.length;
-        let closed = false;
-        while (i < n) {
-            if (src[i] === "\\") {
-                i += 2;
+        const triple = src.startsWith(q + q + q, i);
+        const close = triple ? q + q + q : q;
+        let j = i + close.length;
+        let end = -1;
+        while (j < src.length) {
+            if (src[j] === "\\") {
+                j += 2;
                 continue;
             }
-            if (src.startsWith(quote, i)) {
-                i += quote.length;
-                closed = true;
+            if (src.startsWith(close, j)) {
+                end = j + close.length;
                 break;
             }
             // Only a triple-quoted literal may hold a raw newline.
-            if (src[i] === "\n" && !triple)
+            if (src[j] === "\n" && !triple)
                 break;
-            i++;
-        }
-        if (!closed) {
-            i = start + 1;
-            continue;
+            j++;
         }
-        blank(start + quote.length, i - quote.length);
+        if (end === -1)
+            continue; // never closed: not a literal
+        out.push({ start: i, end });
+        i = end - 1;
+    }
+    return out;
+}
+/** Comments and string CONTENTS blanked (quotes kept, line count preserved). Python
+ *  comments are `#…`; TS/JS go through the shared stripper. */
+/** String CONTENTS blanked (quotes kept, comments kept, line count preserved). */
+export function blankStrings(src, spec) {
+    if (spec.language !== "python")
+        return stripStrings(src);
+    return blankPythonStrings(src);
+}
+/**
+ * String CONTENTS blanked in Python source, quotes kept, offsets and line count
+ * preserved.
+ *
+ * Reads its literals from `pythonStringSpans` — the same scan `stringSpansOf` serves —
+ * so ONE definition decides what a Python literal is, for the callers that blank a
+ * literal and the callers that must copy one through unchanged.
+ *
+ * A line-by-line regex cannot do this. A `"""…"""` block spans lines, so a `#` inside a
+ * docstring or an embedded SQL block read as a comment, and every scanner built on this
+ * then treated quoted text as code the file executes — the delivery-time marker strip
+ * deleted a line out of a value rather than out of a comment, and a `def` at column 0
+ * inside a docstring ended a helper early and reappeared as a second definition of the
+ * same name.
+ */
+function blankPythonStrings(src) {
+    const out = src.split("");
+    for (const { start, end } of pythonStringSpans(src)) {
+        // The quote delimiters stay: callers read this copy for offsets and expect a
+        // literal to still look like one.
+        const q = src.startsWith(src[start].repeat(3), start) ? 3 : 1;
+        for (let i = start + q; i < end - q; i++)
+            out[i] = src[i] === "\n" ? "\n" : " ";
     }
     return out.join("");
 }
@@ -508,6 +540,47 @@ function signatureLines(body) {
     }
     return out;
 }
+/** The index of the first line of the decorator stack above `start`, or `start` when
+ *  there is none. Comments and blank lines may sit between decorators; anything else
+ *  ends the stack.
+ *
+ *  A decorator may span lines — `@retry(` … `)` — so the walk goes up by EXPRESSION,
+ *  not by line: from a line that closes more brackets than it opens, it keeps going
+ *  until the brackets balance, and only then asks whether that line starts with `@`.
+ *  A line-at-a-time walk sees `)` above the definition, stops there, and drops the
+ *  whole decorator out of the comparison.
+ *
+ *  Brackets are counted on `structure`, the copy with comments and string contents
+ *  blanked, for the same reason every other structural read here uses it: a bracket
+ *  typed inside a string (`retry_if_message(")")`) is not a bracket. The `@` itself is
+ *  read from `lines`, where it is still legible. Both copies keep the same line count,
+ *  so one index walks both.
+ *
+ *  Language-neutral: a definition with no `@` line simply gets `start` back. */
+function decoratorStart(lines, structure, start) {
+    let first = start;
+    let depth = 0;
+    for (let i = start - 1; i >= 0; i--) {
+        const l = lines[i].trim();
+        // Blank, or a comment: `structure` has comments blanked already, so the test
+        // is one and the same in every language — no prefix list to keep in step.
+        if (depth === 0 && (structure[i] ?? "").trim() === "")
+            continue;
+        for (const ch of structure[i] ?? "") {
+            if (")]}".includes(ch))
+                depth++;
+            else if ("([{".includes(ch))
+                depth--;
+        }
+        if (depth > 0)
+            continue; // inside a wrapped expression; keep walking up
+        depth = 0;
+        if (!l.startsWith("@"))
+            break;
+        first = i;
+    }
+    return first;
+}
 /** Whether the def at `start` carries `@overload` / `@typing.overload` anywhere in
  *  its decorator stack (comments and other decorators may sit between). */
 function isOverloadStub(lines, start) {