realapi-check 0.1.0 → 0.1.1

package/dist/analyzer.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import { createRequire } from "node:module";
 import ts from "typescript";
 import { collectProjectDeclarations, collectSourceFiles, isDeclarationFile, normalize, } from "./files.js";
-import { declaredDependencies, installedTypesPackages, isBuiltin, isInstalled, installedVersion, missingFromRegistry, packageNameOf, packageOfFile, usesPnp, } from "./packages.js";
+import { declaredDependencies, installedTypesPackages, isBuiltin, isInstalled, installedVersion, missingFromRegistry, packageNameOf, packageOfFile, runtimeSources, usesPnp, } from "./packages.js";
 // TypeScript diagnostics that mean "the code uses an API the types don't have".
 const MISSING_EXPORT_CODES = new Set([2305, 2724, 2614, 2459, 2460]);
 const MISSING_MEMBER_CODES = new Set([2339, 2551]);
@@ -220,7 +220,26 @@ export async function check(opts = {}) {
             return undefined;
         if (kind === "missing-member" && isModuleType(ownerType))
             kind = "missing-export";
-        return { kind, owner, ownerLabel: checker.typeToString(ownerType) };
+        const name = ts.isIdentifier(node) || ts.isStringLiteralLike(node) ? node.text : undefined;
+        // On a union, TypeScript errors unless *every* member has the property.
+        // If any member has it, the API is real and the code just needs narrowing.
+        if (name && ownerType.isUnion() && ownerType.types.some((t) => checker.getPropertyOfType(t, name))) {
+            return undefined;
+        }
+        // Long anonymous types read badly; name the expression instead.
+        let ownerLabel = checker.typeToString(ownerType);
+        const access = ts.isPropertyAccessExpression(parent) ? parent : undefined;
+        if (access && ownerLabel.length > 60)
+            ownerLabel = access.expression.getText();
+        // `doc.internal.getNumberOfPages()` when the real API is `doc.getNumberOfPages()`.
+        let suggestion;
+        if (name && access && ts.isPropertyAccessExpression(access.expression)) {
+            const grandparent = access.expression.expression;
+            if (checker.getPropertyOfType(checker.getTypeAtLocation(grandparent), name)) {
+                suggestion = `${grandparent.getText()}.${name}`;
+            }
+        }
+        return { kind, owner, ownerLabel, suggestion };
     };
     const issues = [];
     const checkedPackages = new Map();
@@ -308,6 +327,24 @@ export async function check(opts = {}) {
         const d = display(p);
         return d.version ? `${d.name}@${d.version}` : d.name;
     };
+    /**
+     * Plugins such as jspdf-autotable add members to their host's objects at
+     * runtime (`doc.lastAutoTable = table`) without typing them. If an
+     * imported package that depends on the owner assigns this member in its
+     * runtime code, the member is real.
+     */
+    const addedByPlugin = (owner, name) => {
+        const host = display(owner).name;
+        const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const assignment = new RegExp(`\\.${escaped}\\s*=(?!=)`);
+        for (const pkg of imported.values()) {
+            if (pkg.rawName === owner.rawName || !pkg.dependencies.includes(host))
+                continue;
+            if (runtimeSources(pkg.root).some((code) => assignment.test(code)))
+                return true;
+        }
+        return false;
+    };
     const displayFields = (p) => {
         const d = display(p);
         return { package: d.name, version: d.version };
@@ -343,7 +380,9 @@ export async function check(opts = {}) {
     for (const { sf, start, message: tsMessage, located, name } of found) {
         if (located.kind === "missing-member" && assigned.has(memberKey(located, name)))
             continue;
-        const suggestion = suggestionFrom(tsMessage);
+        if (located.kind === "missing-member" && addedByPlugin(located.owner, name))
+            continue;
+        const suggestion = suggestionFrom(tsMessage) ?? located.suggestion;
         const where = versioned(located.owner);
         let message;
         if (located.kind === "missing-export") {
@@ -388,6 +427,8 @@ export async function check(opts = {}) {
                     .find((t) => t.name === "deprecated")
                     ?.text?.map((p) => p.text)
                     .join("")
+                    // `{@link register}` / `{@link Foo | text}` → `register` / `text`.
+                    .replace(/\{@link(?:code|plain)?\s+([^}|]+?)(?:\s*\|\s*([^}]+))?\s*\}/g, (_, target, text) => text ?? target)
                     .replace(/\s+/g, " ")
                     .trim();
                 const name = symbol.getName();

package/dist/packages.d.ts

@@ -35,3 +35,5 @@ export declare function declaredDependencies(cwd: string): Set<string>;
 export declare function installedTypesPackages(cwd: string): string[];
 /** Returns true when the npm registry has no package with this name. */
 export declare function missingFromRegistry(name: string): Promise<boolean | undefined>;
+/** The runtime entry files of a package (main, module, exports), read as text. */
+export declare function runtimeSources(root: string): string[];

package/dist/packages.js

@@ -173,3 +173,42 @@ export async function missingFromRegistry(name) {
         return undefined;
     }
 }
+const sourceCache = new Map();
+/** The runtime entry files of a package (main, module, exports), read as text. */
+export function runtimeSources(root) {
+    const cached = sourceCache.get(root);
+    if (cached)
+        return cached;
+    const files = new Set();
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+        const collect = (value) => {
+            if (typeof value === "string") {
+                if (/\.[cm]?js$/.test(value))
+                    files.add(value);
+            }
+            else if (value && typeof value === "object") {
+                for (const [key, nested] of Object.entries(value))
+                    if (key !== "types")
+                        collect(nested);
+            }
+        };
+        collect(pkg.main ?? "index.js");
+        collect(pkg.module);
+        collect(pkg.exports);
+    }
+    catch {
+        // No readable package.json.
+    }
+    const sources = [];
+    for (const file of files) {
+        try {
+            sources.push(fs.readFileSync(path.join(root, file), "utf8"));
+        }
+        catch {
+            // Missing entry file.
+        }
+    }
+    sourceCache.set(root, sources);
+    return sources;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "realapi-check",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Catch AI-hallucinated imports, methods and options that don't exist in the package versions you actually have installed.",
   "type": "module",
   "bin": {