supercov 0.0.41 → 0.0.43

package/analyzers/typescript/src/native-frontend.ts

@@ -0,0 +1,315 @@
+/** Adapter for the exact TypeScript 7.0.2 API, not a legacy compiler fallback. */
+import type ts from "typescript";
+import { createRequire, isBuiltin } from "node:module";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { analysisPath } from "./compiler.js";
+import {
+  selectedRootFiles,
+  type CompilerFrontend,
+  type SyntaxAPI,
+} from "./frontend.js";
+
+// The optional project dependency cannot be imported by the TS5 build. Native API
+// objects are confined to this adapter; its public surface is the shared frontend.
+type Native = any;
+
+export function nativeFrontend(
+  entry: string,
+  projectRoot: string,
+): CompilerFrontend {
+  const [major, minor] = process.versions.node.split(".").map(Number);
+  if (major < 22 || (major === 22 && minor < 12))
+    throw new Error(
+      "The TypeScript 7 frontend requires Node 22.12 or newer (Node 24 is tested)",
+    );
+  const require = createRequire(pathToFileURL(entry));
+  const ast: Native = require("typescript/unstable/ast");
+  const native: Native = require("typescript/unstable/sync");
+  const root = analysisPath(projectRoot);
+  const key = (file: string) => analysisPath(file).replaceAll("\\", "/");
+  const virtual = new Map<string, string>();
+  let parseSerial = 0;
+  const opened = new Set<string>();
+  const limitations = new Set<string>();
+  let api: Native;
+  let snapshot: Native;
+  let closed = false;
+  function client() {
+    if (closed) throw new Error("TypeScript 7 frontend is closed");
+    return (api ??= new native.API({
+      cwd: root,
+      fs: {
+        readFile: (file: string) => virtual.get(key(file)),
+        fileExists: (file: string) =>
+          virtual.has(key(file)) ? true : undefined,
+      },
+    }));
+  }
+  function update(config: string) {
+    const previous = snapshot;
+    snapshot = client().updateSnapshot({
+      ...(!opened.has(config) ? { openProjects: [config] } : {}),
+      fileChanges: { invalidateAll: true },
+    });
+    opened.add(config);
+    previous?.dispose();
+    const project = snapshot.getProject(config);
+    if (!project)
+      throw new Error(
+        `TypeScript 7 did not open the analysis project: ${config}`,
+      );
+    return project;
+  }
+  function overlayConfig(path: string, config: unknown) {
+    if (existsSync(path))
+      throw new Error(`Reserved analysis config already exists: ${path}`);
+    virtual.set(key(path), JSON.stringify(config));
+  }
+  const kinds = ast.SyntaxKind;
+  const functionKinds = new Set(
+    [
+      "FunctionDeclaration",
+      "MethodDeclaration",
+      "Constructor",
+      "GetAccessor",
+      "SetAccessor",
+      "FunctionExpression",
+      "ArrowFunction",
+      "MethodSignature",
+      "CallSignature",
+      "JSDocSignature",
+      "ConstructSignature",
+      "IndexSignature",
+      "FunctionType",
+      "JSDocFunctionType",
+      "ConstructorType",
+    ]
+      .map((name) => kinds[name])
+      .filter((value) => typeof value === "number"),
+  );
+  const loopKinds = new Set(
+    [
+      "ForStatement",
+      "ForInStatement",
+      "ForOfStatement",
+      "WhileStatement",
+      "DoStatement",
+    ].map((name) => kinds[name]),
+  );
+  // These adapters preserve native nodes and native enum values. No TS5 predicate
+  // may inspect a TS7 node: syntax-kind numeric values are different.
+  const syntax = {
+    ...ast,
+    SymbolFlags: native.SymbolFlags,
+    forEachChild: (node: Native, visit: Native, visitArray?: Native) =>
+      node.forEachChild(visit, visitArray),
+    isFunctionLike: (node: Native) => !!node && functionKinds.has(node.kind),
+    isIterationStatement: (
+      node: Native,
+      lookInLabeledStatements: boolean,
+    ): boolean =>
+      !!node &&
+      (loopKinds.has(node.kind) ||
+        (lookInLabeledStatements &&
+          node.kind === kinds.LabeledStatement &&
+          syntax.isIterationStatement(node.statement, true))),
+    isMethodSignature: ast.isMethodSignatureDeclaration,
+    isParameter: ast.isParameterDeclaration,
+    isTypeAssertionExpression: ast.isTypeAssertion,
+    isStringLiteralLike: (node: Native) =>
+      !!node &&
+      (node.kind === kinds.StringLiteral ||
+        node.kind === kinds.NoSubstitutionTemplateLiteral),
+    canHaveModifiers: (node: Native) => !!node && "modifiers" in node,
+    getModifiers: (node: Native) =>
+      node.modifiers?.filter((m: Native) => m.kind !== kinds.Decorator),
+  } as unknown as SyntaxAPI;
+  for (const name of [
+    "isMethodSignature",
+    "isParameter",
+    "isTypeAssertionExpression",
+    "getLeadingCommentRanges",
+    "getTrailingCommentRanges",
+  ] as const)
+    if (typeof syntax[name] !== "function")
+      throw new Error(`Unsupported TypeScript 7 syntax API: ${name}`);
+
+  const frontend: CompilerFrontend = {
+    kind: "typescript-native-7",
+    version: "7.0.2",
+    syntax,
+    limitations,
+    close() {
+      if (closed) return;
+      closed = true;
+      try {
+        snapshot?.dispose();
+      } finally {
+        api?.close();
+      }
+    },
+    parseSource(file, text) {
+      const absolute = resolve(root, file);
+      virtual.set(key(absolute), text);
+      // Do not rely on 7.0.2 reloading an edited virtual config's root-file list.
+      const parseConfig = resolve(
+        root,
+        `.supercov-asserted-parse-${++parseSerial}.tsconfig.json`,
+      );
+      overlayConfig(parseConfig, {
+        files: [absolute],
+        compilerOptions: {
+          allowJs: true,
+          checkJs: true,
+          noResolve: true,
+          noLib: true,
+          noEmit: true,
+          types: [],
+        },
+      });
+      const project = update(parseConfig);
+      const source = project.program.getSourceFile(absolute);
+      if (!source || source.text !== text)
+        throw new Error(`Native parser source mismatch: ${file}`);
+      const errors = project.program.getSyntacticDiagnostics(absolute);
+      if (errors.length)
+        throw new Error(
+          `Native parser rejected ${file}: ${JSON.stringify(errors)}`,
+        );
+      return source as ts.SourceFile;
+    },
+    openProgram(options) {
+      const configPath = resolve(root, options.tsconfig ?? "tsconfig.json");
+      const hasConfig = existsSync(configPath);
+      if (!hasConfig && !options.sourceFiles)
+        throw new Error(`Missing TypeScript config: ${configPath}`);
+      const configured = hasConfig
+        ? client().parseConfigFile(configPath).fileNames
+        : [];
+      const files = selectedRootFiles(options, configured);
+      const overlay = resolve(
+        dirname(configPath),
+        ".supercov-asserted-query.tsconfig.json",
+      );
+      overlayConfig(overlay, {
+        ...(hasConfig ? { extends: configPath } : {}),
+        files,
+        include: [],
+        exclude: [],
+        compilerOptions: {
+          ...(options.sourceFiles ? { allowJs: true, checkJs: true } : {}),
+          noEmit: true,
+        },
+      });
+      const project = update(overlay);
+      const program = project.program;
+      const configErrors = program.getConfigFileParsingDiagnostics();
+      if (configErrors.length)
+        throw new Error(
+          `TypeScript 7 configuration is invalid: ${JSON.stringify(configErrors)}`,
+        );
+      const checker = project.checker;
+      const symbols = new WeakMap<object, ts.Symbol>();
+      const nativeSymbols = new WeakMap<object, Native>();
+      function wrapSymbol(symbol: Native): ts.Symbol | undefined {
+        if (!symbol) return undefined;
+        let wrapped = symbols.get(symbol);
+        if (!wrapped) {
+          wrapped = {
+            flags: symbol.flags,
+            name: symbol.name,
+            escapedName: symbol.escapedName,
+            get valueDeclaration() {
+              return symbol.valueDeclaration?.resolve(project);
+            },
+            get declarations() {
+              return symbol.declarations.map((handle: Native) => {
+                const node = handle.resolve(project);
+                if (!node)
+                  throw new Error(
+                    "TypeScript 7 declaration handle did not resolve",
+                  );
+                return node;
+              });
+            },
+          } as ts.Symbol;
+          symbols.set(symbol, wrapped);
+          nativeSymbols.set(wrapped, symbol);
+        }
+        return wrapped;
+      }
+      const allFiles: ts.SourceFile[] = program
+        .getSourceFileNames()
+        .map((file: string) => {
+          const source = program.getSourceFile(file);
+          if (!source) throw new Error(`Native source disappeared: ${file}`);
+          return source;
+        });
+      const resolutionCache = new Map<string, string | undefined>();
+      return {
+        files: allFiles,
+        checker: {
+          getSymbolAtLocation: (node) =>
+            wrapSymbol(checker.getSymbolAtLocation(node)),
+          getShorthandAssignmentValueSymbol: (node) =>
+            wrapSymbol(checker.getShorthandAssignmentValueSymbol(node)),
+          getAliasedSymbol: (symbol) => {
+            const original = nativeSymbols.get(symbol);
+            if (!original)
+              throw new Error("Symbol belongs to a different compiler session");
+            return wrapSymbol(checker.getAliasedSymbol(original))!;
+          },
+          getResolvedSignature: (node) => {
+            const signature = checker.getResolvedSignature(node);
+            return signature
+              ? ({
+                  getParameters: () =>
+                    signature.getParameters().map(wrapSymbol),
+                } as ts.Signature)
+              : undefined;
+          },
+        },
+        resolveModule(specifier, from) {
+          const cacheKey = `${key(from)}\0${specifier}`;
+          if (resolutionCache.has(cacheKey))
+            return resolutionCache.get(cacheKey);
+          const source = program.getSourceFile(from);
+          const paths = new Set<string>();
+          const visit = (node: Native) => {
+            if (syntax.isStringLiteralLike(node) && node.text === specifier) {
+              // Ask the native checker about actual module-reference syntax. A
+              // vi.mock string is not a TypeScript import and is not guessed.
+              const p: Native = node.parent;
+              if (
+                p &&
+                (ast.isImportDeclaration(p) ||
+                  ast.isExportDeclaration(p) ||
+                  (ast.isCallExpression(p) &&
+                    p.expression.kind === kinds.ImportKeyword))
+              ) {
+                const symbol = checker.getSymbolAtLocation(node);
+                for (const handle of symbol?.declarations ?? []) {
+                  const declaration = handle.resolve(project);
+                  if (declaration && syntax.isSourceFile(declaration))
+                    paths.add(declaration.fileName);
+                }
+              }
+            }
+            node.forEachChild(visit);
+          };
+          if (source) visit(source);
+          const result = paths.size === 1 ? [...paths][0] : undefined;
+          if (!result && !isBuiltin(specifier))
+            limitations.add(
+              `native-module-resolution: ${key(from)} → ${specifier}`,
+            );
+          resolutionCache.set(cacheKey, result);
+          return result;
+        },
+      };
+    },
+  };
+  return frontend;
+}

package/analyzers/typescript/src/pragmas.ts

@@ -0,0 +1,218 @@
+import type ts from "typescript";
+import type { Site } from "./types.js";
+
+export type AssertionPhase = { source?: string; op: string; status?: string };
+export function assertionWitnessIssue(
+  phases: AssertionPhase[] | undefined,
+  source?: string,
+  method?: string,
+) {
+  const matches = (phases ?? []).filter(
+    (p) => p.source === source && p.op.split(".").pop() === method,
+  );
+  if (source && matches.length && matches.every((p) => p.status === "passed"))
+    return undefined;
+  const statuses = new Set(matches.map((p) => p.status ?? "unknown"));
+  return !phases
+    ? ("capture-unavailable" as const)
+    : !source
+      ? ("uninstrumented-observation" as const)
+      : !matches.length
+        ? ("call-not-recorded" as const)
+        : statuses.size > 1
+          ? ("mixed-call-outcomes" as const)
+          : statuses.has("failed")
+            ? ("call-failed" as const)
+            : ("call-incomplete" as const);
+}
+
+interface Attachment {
+  testKey: string;
+  source: string;
+  method: string;
+  inert: boolean;
+}
+interface Comment {
+  id: string;
+  where: string;
+  raw: string;
+  target?: { file: string; function: string; snippet?: string; via?: string };
+  candidateSites: string[];
+  issue?: string;
+  attachments: Attachment[];
+}
+export interface PragmaHint {
+  id: string;
+  where: string;
+  raw: string;
+  target?: Comment["target"];
+  candidateSites: string[];
+  issue?: string;
+  test?: string;
+  assertionSource?: string;
+  assertionMethod?: string;
+  witness: "passed" | "unavailable";
+  witnessIssue?: string;
+}
+
+/** Source hints are kept OUT of observations. A comment never adds a boundary. */
+export function collectPragmas(
+  compiler: import("./frontend.js").SyntaxAPI,
+  files: ts.SourceFile[],
+  relativeFile: (file: ts.SourceFile) => string,
+  sites: Site[],
+) {
+  const comments = new Map<string, Comment>();
+  const key = (sf: ts.SourceFile, pos: number) => `${relativeFile(sf)}:${pos}`;
+  const location = (sf: ts.SourceFile, pos: number) => {
+    const p = sf.getLineAndCharacterOfPosition(pos);
+    return `${relativeFile(sf)}:${p.line + 1}:${p.character + 1}`;
+  };
+  for (const sf of files) {
+    const collect = (ranges: ts.CommentRange[] | undefined) => {
+      for (const range of ranges ?? []) {
+        const raw = sf.text.slice(range.pos, range.end);
+        if (!/^\/\/\s*observes:/.test(raw) || comments.has(key(sf, range.pos)))
+          continue;
+        const parsed = /^\/\/\s*observes:\s*(\S+?)#(\S+)(?:\s+(.+?))?\s*$/.exec(
+          raw,
+        );
+        const suffix = parsed?.[3]?.split(/(?:^|\s+)via\s+/);
+        const target = parsed
+          ? {
+              file: parsed[1],
+              function: parsed[2],
+              snippet: suffix?.[0]?.trim() || undefined,
+              via: suffix?.slice(1).join(" via ").trim() || undefined,
+            }
+          : undefined;
+        const validPath =
+          target &&
+          !/[\\:]/.test(target.file) &&
+          target.file
+            .split("/")
+            .every((part) => part && part !== "." && part !== "..");
+        const candidates = validPath
+          ? sites
+              .filter(
+                (s) =>
+                  s.file === target.file &&
+                  (s.owner === target.function || s.fn === target.function) &&
+                  (!target.snippet || s.text.includes(target.snippet)),
+              )
+              .map((s) => s.id)
+          : [];
+        comments.set(key(sf, range.pos), {
+          id: location(sf, range.pos),
+          where: location(sf, range.pos),
+          raw,
+          target,
+          candidateSites: candidates,
+          issue: !target
+            ? "invalid-syntax"
+            : !validPath
+              ? "invalid-target-path"
+              : !candidates.length
+                ? "target-not-in-inventory"
+                : candidates.length > 1
+                  ? "ambiguous-target"
+                  : undefined,
+          attachments: [],
+        });
+      }
+    };
+    const visit = (node: ts.Node) => {
+      collect(compiler.getLeadingCommentRanges(sf.text, node.getFullStart()));
+      collect(compiler.getTrailingCommentRanges(sf.text, node.getEnd()));
+      compiler.forEachChild(node, visit);
+    };
+    visit(sf);
+  }
+  return {
+    register(
+      node: ts.CallExpression,
+      method: string,
+      testKey: string,
+      inert: boolean,
+    ) {
+      let statement: ts.Node = node;
+      while (statement.parent && !compiler.isStatement(statement))
+        statement = statement.parent;
+      // A comment on an if/block/declaration is not a claim about every assertion inside it.
+      if (!compiler.isExpressionStatement(statement)) return;
+      const sf = node.getSourceFile();
+      for (const range of compiler.getLeadingCommentRanges(
+        sf.text,
+        statement.getFullStart(),
+      ) ?? []) {
+        const comment = comments.get(key(sf, range.pos));
+        if (!comment) continue;
+        const attachment = {
+          testKey,
+          source: location(sf, node.getStart(sf)),
+          method,
+          inert,
+        };
+        if (
+          !comment.attachments.some(
+            (a) =>
+              a.testKey === testKey &&
+              a.source === attachment.source &&
+              a.method === method,
+          )
+        )
+          comment.attachments.push(attachment);
+      }
+    },
+    finish(
+      bindings: { testKey: string; id: string; phases?: AssertionPhase[] }[],
+    ): PragmaHint[] {
+      return [...comments.values()].flatMap<PragmaHint>(
+        ({ attachments, ...comment }) => {
+          const sources = new Set(
+            attachments.map((a) => `${a.source}#${a.method}`),
+          );
+          const issue =
+            comment.issue ??
+            (sources.size > 1
+              ? "ambiguous-assertion"
+              : !sources.size
+                ? "unattached-assertion"
+                : undefined);
+          const matched = bindings.flatMap((b) =>
+            attachments
+              .filter((a) => a.testKey === b.testKey && !a.inert)
+              .map((a) => ({ a, b })),
+          );
+          if (sources.size !== 1 || !matched.length)
+            return [
+              {
+                ...comment,
+                issue: issue ?? "no-owning-passed-test",
+                witness: "unavailable" as const,
+              },
+            ];
+          return matched.map(({ a, b }) => {
+            const witnessIssue = assertionWitnessIssue(
+              b.phases,
+              a.source,
+              a.method,
+            );
+            return {
+              ...comment,
+              id: `${comment.id}@${b.id}`,
+              issue,
+              test: b.id,
+              assertionSource: a.source,
+              assertionMethod: a.method,
+              witness: witnessIssue
+                ? ("unavailable" as const)
+                : ("passed" as const),
+              witnessIssue,
+            };
+          });
+        },
+      );
+    },
+  };
+}

package/analyzers/typescript/src/types.ts

@@ -0,0 +1,45 @@
+/** Source inventory supplied by the frontend. Positions are original-source UTF-16 offsets. */
+export interface Site {
+  id: string;
+  file: string;
+  kind: "decision" | "effect";
+  category: string;
+  classification: "contractual" | "incidental" | "review";
+  start: { line: number; column: number };
+  end: { line: number; column: number };
+  pos: number;
+  endPos: number;
+  text: string;
+  fn: string;
+  owner: string;
+  exported: boolean;
+  note?: string;
+  chain?: string[];
+  method?: string;
+  arg0?: string;
+}
+
+export interface AnalyzeOptions {
+  projectRoot: string;
+  /** Query-local evidence supplied in memory by the archive adapter, using original-source positions. */
+  evidenceFiles: Record<string, string>;
+  /** Exact files selected by the archive integration, including JS and nonstandard test directories. */
+  sourceFiles?: string[];
+  testFiles?: string[];
+  sourceDir?: string;
+  testDir?: string;
+  tsconfig?: string;
+  /** Defaults to the compiler API installed in the project being analyzed. */
+  typescript?: typeof import("typescript");
+}
+
+export interface AnalysisDiagnostics {
+  runtimeTests: number;
+  linkedTests: number;
+  staticTests: number;
+  linkedByAssertionLines: number;
+  linkedByTitle: number;
+  linkWarnings: string[];
+  unrecognizedOperands: { shape: string; count: number }[];
+  compilerVersion: string;
+}

package/analyzers/typescript/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "skipLibCheck": true,
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts"]
+}

package/docs/agent-loop.md

@@ -59,6 +59,19 @@ The `line` query is useful before writing a test because it shows which tests
 already reach that line. Extending a nearby test is often better than adding a
 duplicate.
 
+For supported JS/TS projects, inspect assertion evidence before adding tests:
+
+```sh
+npx supercov runs latest assertions --file app/checkout/session.ts --limit 5 --json
+npx supercov runs latest assertions --pragmas --json
+```
+
+This post-run query needs the matching source and a compatible
+project TypeScript API. An `evident` candidate is not a proof of safety; keep
+test gaps separate from analysis limits. Follow the returned evidence pointers
+and `pagination.nextOffset`, pinning `--analysis` and the run id while paging.
+See [assertion evidence](assertion-evidence.md) for requirements and examples.
+
 ## A complete prompt for longer runs
 
 ```text