realapi-check 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Naveen Elango
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# realapi-check
+
+**Catch AI-hallucinated imports, methods and options before they reach runtime.**
+
+AI coding assistants write code for the library version they were trained on, not the one you installed. They invent functions, misspell methods, pass options that were removed, and import packages that don't exist. `realapi` checks your code against the **exact package versions in your `node_modules`** and tells you what isn't real.
+
+```
+$ npx realapi-check
+
+src/user.ts
+  7:22     error    'emial' does not exist on ZodString (zod@4.6.5). Did you mean 'email'?  missing-member
+                    const s = z.string().emial();
+  9:34     error    'retries' is not a known option of AxiosRequestConfig (axios@1.20.0)  unknown-option
+                    axios.get("/x", { timeout: 1000, retries: 3 });
+  3:10     error    'readFileAsync' is not exported by @types/node@26.6.3. Did you mean 'readFileSync'?  missing-export
+                    import { readFileAsync } from "node:fs";
+  5:32     error    'express-useragent-pro' does not exist on npm. It was probably invented; do not install it blindly  missing-package
+                    import { parseUserAgent } from "express-useragent-pro";
+  10:29    warning  'merge' is deprecated in zod@4.6.5: Use A.extend(B.shape) instead.  deprecated
+                    const merged = a.merge(b);
+
+✖ 5 problems (4 errors, 1 warning) checked 42 files against 12 installed packages
+```
+
+## What it catches
+
+| Kind | Example |
+|---|---|
+| `missing-export` | `import { groupByKey } from "lodash"`, `const { makeClient } = require("x")` |
+| `missing-member` | `app.listenAsync()`, `z.string().emial()` |
+| `unknown-option` | `axios.get(url, { retries: 3 })` |
+| `missing-package` | Importing a package that isn't installed. With `--online`, it also checks whether the package exists on npm at all. |
+| `deprecated` (warning) | APIs marked `@deprecated` in your installed version, with the suggested replacement |
+
+It works on **TypeScript and plain JavaScript** (`import` and `require`), with or without a `tsconfig.json`.
+
+## Why not just run `tsc`?
+
+- **JavaScript projects** don't have `tsc` checking them at all. realapi type-checks JS against the packages' own type definitions.
+- **It reports only package API problems.** A `tsc` run on a large project can print hundreds of unrelated errors. realapi keeps only the ones where your code uses something a package doesn't provide.
+- **Readable output.** Each problem names the package *and the installed version*, suggests the closest real name, and separates "not installed" from "doesn't exist".
+- **It's honest about coverage.** Packages that ship no types are listed as *not verified*, rather than silently passing.
+
+## Usage
+
+```bash
+npx realapi-check              # check the whole project
+npx realapi-check src/ scripts/ # check specific paths
+npx realapi-check --json       # machine-readable output for CI or AI agents
+npx realapi-check --online     # also look up missing packages on the npm registry
+```
+
+Installed as a dev dependency (`npm i -D realapi-check`), the command is also available under the shorter name `realapi`.
+
+| Option | Description |
+|---|---|
+| `-p, --project <file>` | tsconfig/jsconfig to use (auto-detected by default) |
+| `--json` | Print results as JSON |
+| `--online` | Check missing packages against registry.npmjs.org |
+| `--no-deprecated` | Don't report deprecated APIs |
+| `--strict` | Exit with code 1 on warnings too |
+
+**Exit codes:** `0` clean, `1` problems found, `2` usage or runtime error.
+
+### Ignoring a line
+
+```ts
+// realapi-ignore
+client.addedAtRuntimeByAPlugin();
+```
+
+### In CI
+
+```yaml
+- run: npm ci
+- run: npx realapi-check
+```
+
+### With AI agents
+
+Add this to your agent instructions (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`):
+
+> After changing code, run `npx realapi-check --json` and fix every reported issue before finishing.
+
+The JSON output includes the file, line, symbol, package, version and suggestion for each problem, so an agent can fix its own mistakes.
+
+## Programmatic API
+
+```ts
+import { check, formatPretty } from "realapi-check";
+
+const result = await check({ cwd: process.cwd(), paths: ["src"] });
+console.log(formatPretty(result));
+// result.issues, result.packagesChecked, result.unverifiable
+```
+
+## How it works
+
+realapi builds a TypeScript program over your project with `allowJs` and `checkJs` enabled, using your `tsconfig.json` settings when one exists. It takes the compiler's "does not exist" diagnostics and keeps only those whose target type is **declared inside `node_modules`**. That covers packages' own types, `@types/*`, and the Node built-ins. Your own code, TypeScript's standard library, and shapes derived from your data (such as `z.infer<...>`) are ignored, so it reports only real mismatches with package APIs. Module augmentation (`declare module "express" { ... }`) and tsconfig `paths` aliases are respected.
+
+## Limitations
+
+- Packages without type definitions can't be verified. They are listed in the summary.
+- `.vue`, `.svelte` and `.astro` files aren't checked yet.
+- In monorepos, run it once per package so each one uses its own `tsconfig.json`.
+- Properties your own code assigns (`app.db = pool`, `req.user = decoded`) are treated as yours and never reported. Properties added by a *third-party* plugin that ships no types will be reported; add types for them or use `// realapi-ignore`.
+- With a `tsconfig.json`, the files checked are the ones its `include`/`exclude` select. As with `tsc`, a `.js` file next to a `.ts` file with the same name is treated as build output and skipped.
+
+## License
+
+MIT

package/dist/analyzer.d.ts

@@ -0,0 +1,2 @@
+import type { CheckOptions, CheckResult } from "./types.js";
+export declare function check(opts?: CheckOptions): Promise<CheckResult>;

package/dist/analyzer.js

@@ -0,0 +1,491 @@
+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";
+// 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]);
+const UNKNOWN_OPTION_CODES = new Set([2353, 2561]);
+const DEPRECATED_CODES = new Set([6385, 6387]);
+const IGNORE_COMMENT = /realapi-ignore\b/;
+const tsLibDir = normalize(path.dirname(createRequire(import.meta.url).resolve("typescript")));
+function loadCompilerOptions(cwd, project) {
+    const configPath = project
+        ? path.resolve(cwd, project)
+        : ts.findConfigFile(cwd, ts.sys.fileExists, "tsconfig.json") ??
+            ts.findConfigFile(cwd, ts.sys.fileExists, "jsconfig.json");
+    let options = {
+        target: ts.ScriptTarget.ES2022,
+        module: ts.ModuleKind.Preserve,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+        jsx: ts.JsxEmit.Preserve,
+        strict: false,
+    };
+    let fileNames;
+    if (configPath && ts.sys.fileExists(configPath)) {
+        const read = ts.readConfigFile(configPath, ts.sys.readFile);
+        if (read.error) {
+            throw new Error(`Could not read ${configPath}: ${ts.flattenDiagnosticMessageText(read.error.messageText, "\n")}`);
+        }
+        // allowJs up front so the project's include patterns pick up JS files too.
+        const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, path.dirname(configPath), { allowJs: true }, configPath);
+        options = parsed.options;
+        fileNames = parsed.fileNames.map(normalize);
+    }
+    else if (project) {
+        throw new Error(`Project file not found: ${project}`);
+    }
+    // TypeScript 6 no longer loads every @types package by default. Restore
+    // the long-standing behaviour so Node built-ins and globals resolve.
+    if (options.types === undefined)
+        options.types = installedTypesPackages(cwd);
+    return {
+        options: {
+            ...options,
+            allowJs: true,
+            checkJs: true,
+            noEmit: true,
+            skipLibCheck: true,
+            esModuleInterop: true,
+            allowSyntheticDefaultImports: true,
+            resolveJsonModule: true,
+            incremental: false,
+            composite: false,
+            declaration: false,
+            emitDeclarationOnly: false,
+            maxNodeModuleJsDepth: 0,
+            ignoreDeprecations: "6.0",
+        },
+        fileNames,
+    };
+}
+/** Deepest node whose span contains `pos`. */
+function nodeAt(sf, pos) {
+    let found = sf;
+    const visit = (node) => {
+        if (pos >= node.getStart(sf) && pos < node.getEnd()) {
+            found = node;
+            ts.forEachChild(node, visit);
+        }
+    };
+    ts.forEachChild(sf, visit);
+    return found;
+}
+function flatten(message) {
+    return ts.flattenDiagnosticMessageText(message, "\n");
+}
+function suggestionFrom(message) {
+    return /Did you mean '([^']+)'\?/.exec(message)?.[1];
+}
+export async function check(opts = {}) {
+    const cwd = path.resolve(opts.cwd ?? process.cwd());
+    const reportDeprecated = opts.deprecated ?? true;
+    const { options, fileNames } = loadCompilerOptions(cwd, opts.project);
+    const explicitPaths = opts.paths?.length ? opts.paths : undefined;
+    // With a tsconfig, its include/exclude decide the project (which keeps out
+    // build output and fixtures). Without one, or for explicit paths, walk.
+    const candidates = explicitPaths || !fileNames ? collectSourceFiles(cwd, explicitPaths ?? ["."]) : fileNames;
+    const sources = candidates.filter((f) => !isDeclarationFile(f));
+    const declarations = fileNames ? fileNames.filter(isDeclarationFile) : collectProjectDeclarations(cwd);
+    const rootNames = [...new Set([...sources, ...declarations])];
+    // A language service (rather than a bare Program) is needed for suggestion
+    // diagnostics, which is where TypeScript reports `@deprecated` usage.
+    const host = {
+        getCompilationSettings: () => options,
+        getScriptFileNames: () => rootNames,
+        getScriptVersion: () => "0",
+        getScriptSnapshot: (file) => {
+            const text = ts.sys.readFile(file);
+            return text === undefined ? undefined : ts.ScriptSnapshot.fromString(text);
+        },
+        getCurrentDirectory: () => cwd,
+        getDefaultLibFileName: (o) => ts.getDefaultLibFilePath(o),
+        fileExists: ts.sys.fileExists,
+        readFile: ts.sys.readFile,
+        readDirectory: ts.sys.readDirectory,
+        directoryExists: ts.sys.directoryExists,
+        getDirectories: ts.sys.getDirectories,
+        realpath: ts.sys.realpath,
+    };
+    const service = ts.createLanguageService(host, ts.createDocumentRegistry());
+    const program = service.getProgram();
+    if (!program)
+        throw new Error("TypeScript could not create a program for this project");
+    const checker = program.getTypeChecker();
+    const isExternalFile = (sf) => {
+        if (program.isSourceFileDefaultLibrary(sf))
+            return false;
+        const name = sf.fileName;
+        if (name.startsWith(tsLibDir + "/"))
+            return false;
+        return program.isSourceFileFromExternalLibrary(sf) || name.includes("/node_modules/");
+    };
+    const isAugmentation = (decl) => !!ts.findAncestor(decl, (n) => ts.isModuleDeclaration(n) && ts.isStringLiteral(n.name));
+    /**
+     * The package that declares `symbol`. Project declarations are allowed only
+     * when they augment a package (`declare module "pkg" { ... }`); a symbol
+     * that the project itself defines, or one from TypeScript's libs, has no
+     * external owner.
+     */
+    const externalOwner = (symbol) => {
+        const decls = symbol?.getDeclarations();
+        if (!decls?.length)
+            return undefined;
+        let owner;
+        for (const decl of decls) {
+            // Mapped types (z.infer<...>, Pick<...>) describe the user's own data shapes.
+            if (ts.isMappedTypeNode(decl))
+                return undefined;
+            const sf = decl.getSourceFile();
+            if (isExternalFile(sf))
+                owner ??= packageOfFile(sf.fileName);
+            else if (!isAugmentation(decl))
+                return undefined;
+        }
+        return owner;
+    };
+    /** Owner of a type: every constituent that has a symbol must be external. */
+    const externalOwnerOfType = (type) => {
+        const parts = type.isUnionOrIntersection() ? type.types : [type];
+        let owner;
+        let any = false;
+        for (const part of parts) {
+            const symbol = part.aliasSymbol ?? part.getSymbol();
+            if (!symbol)
+                continue;
+            const o = externalOwner(symbol);
+            if (!o)
+                return undefined;
+            owner ??= o;
+            any = true;
+        }
+        return any ? owner : undefined;
+    };
+    const isModuleType = (type) => {
+        const decls = type.getSymbol()?.getDeclarations() ?? [];
+        return decls.length > 0 && decls.every((d) => ts.isSourceFile(d) || ts.isModuleDeclaration(d));
+    };
+    const moduleSpecifierOwner = (specifier) => {
+        if (!ts.isStringLiteralLike(specifier) || !packageNameOf(specifier.text))
+            return undefined;
+        return externalOwner(checker.getSymbolAtLocation(specifier));
+    };
+    /** Work out which external API a "does not exist" diagnostic is about. */
+    const locate = (node, code) => {
+        const parent = node.parent;
+        if (!parent)
+            return undefined;
+        // import { x } from "pkg" / export { x } from "pkg"
+        if (ts.isImportSpecifier(parent) || ts.isExportSpecifier(parent) || ts.isImportClause(parent)) {
+            const decl = ts.findAncestor(parent, (n) => ts.isImportDeclaration(n) || ts.isExportDeclaration(n));
+            const spec = decl?.moduleSpecifier;
+            if (!spec || !ts.isStringLiteralLike(spec))
+                return undefined;
+            const owner = moduleSpecifierOwner(spec);
+            return owner && { kind: "missing-export", owner, ownerLabel: `"${spec.text}"` };
+        }
+        let ownerType;
+        let kind = "missing-member";
+        if (ts.isPropertyAccessExpression(parent) && parent.name === node) {
+            ownerType = checker.getTypeAtLocation(parent.expression);
+        }
+        else if (ts.isQualifiedName(parent) && parent.right === node) {
+            ownerType = checker.getTypeAtLocation(parent.left);
+            if (!externalOwnerOfType(ownerType)) {
+                const owner = externalOwner(checker.getSymbolAtLocation(parent.left));
+                const sym = checker.getSymbolAtLocation(parent.left);
+                if (owner && sym)
+                    return { kind: "missing-export", owner, ownerLabel: sym.getName() };
+            }
+        }
+        else if (ts.isBindingElement(parent) && ts.isObjectBindingPattern(parent.parent)) {
+            const holder = parent.parent.parent;
+            ownerType =
+                ts.isVariableDeclaration(holder) && holder.initializer
+                    ? checker.getTypeAtLocation(holder.initializer)
+                    : checker.getTypeAtLocation(parent.parent);
+        }
+        else if (UNKNOWN_OPTION_CODES.has(code) &&
+            (ts.isPropertyAssignment(parent) || ts.isShorthandPropertyAssignment(parent) || ts.isMethodDeclaration(parent)) &&
+            ts.isObjectLiteralExpression(parent.parent)) {
+            kind = "unknown-option";
+            ownerType = checker.getContextualType(parent.parent);
+        }
+        if (!ownerType)
+            return undefined;
+        ownerType = checker.getNonNullableType(ownerType);
+        const owner = externalOwnerOfType(ownerType);
+        if (!owner)
+            return undefined;
+        if (kind === "missing-member" && isModuleType(ownerType))
+            kind = "missing-export";
+        return { kind, owner, ownerLabel: checker.typeToString(ownerType) };
+    };
+    const issues = [];
+    const checkedPackages = new Map();
+    const unverifiable = new Map();
+    const missingSpecifiers = [];
+    const declared = declaredDependencies(cwd);
+    const pnp = usesPnp(cwd);
+    const hasNodeTypes = isInstalled("@types/node", cwd);
+    const lineInfo = (sf, pos) => {
+        const { line, character } = sf.getLineAndCharacterOfPosition(pos);
+        const lines = sf.text.split(/\r?\n/);
+        const text = lines[line] ?? "";
+        const prev = lines[line - 1] ?? "";
+        return {
+            line: line + 1,
+            column: character + 1,
+            sourceLine: text.trim(),
+            ignored: IGNORE_COMMENT.test(text) || /^\s*(\/\/|\/\*|\*).*realapi-ignore\b/.test(prev),
+        };
+    };
+    const relative = (sf) => path.relative(cwd, sf.fileName).replace(/\\/g, "/");
+    const push = (sf, pos, issue) => {
+        const info = lineInfo(sf, pos);
+        if (info.ignored)
+            return;
+        issues.push({ ...issue, file: relative(sf), line: info.line, column: info.column, sourceLine: info.sourceLine });
+    };
+    const sourceSet = new Set(sources);
+    const userFiles = program.getSourceFiles().filter((sf) => sourceSet.has(sf.fileName));
+    // 1. Imports: record what was verified, what couldn't be, and what's missing.
+    const imported = new Map();
+    for (const sf of userFiles) {
+        for (const spec of moduleSpecifiers(sf)) {
+            const name = packageNameOf(spec.text);
+            if (!name)
+                continue;
+            const symbol = checker.getSymbolAtLocation(spec);
+            const owner = externalOwner(symbol);
+            if (owner) {
+                imported.set(owner.rawName, owner);
+                continue;
+            }
+            if (symbol)
+                continue; // Resolved to project code or an ambient declaration.
+            if (isBuiltin(spec.text)) {
+                if (!hasNodeTypes)
+                    unverifiable.set("node", { package: "node", reason: "no-node-types" });
+                continue;
+            }
+            if (isAliased(spec.text, options))
+                continue;
+            if (isInstalled(name, path.dirname(sf.fileName)) || pnp) {
+                unverifiable.set(name, { package: name, reason: "no-types" });
+            }
+            else {
+                missingSpecifiers.push({ name, declared: declared.has(name), sf, node: spec });
+            }
+        }
+    }
+    /**
+     * The package to name in messages. Types often live in an internal package
+     * (`Express` is declared in `@types/express-serve-static-core`), so credit
+     * the imported package that depends on it. For `@types/x`, report the
+     * installed runtime version of `x`, which is the version the user knows.
+     */
+    const display = (owner) => {
+        let shown = owner;
+        if (!imported.has(owner.rawName)) {
+            for (const pkg of imported.values()) {
+                if (pkg.dependencies.includes(owner.rawName)) {
+                    shown = pkg;
+                    break;
+                }
+            }
+        }
+        // Built-in typings version isn't Node's version; say where it came from.
+        if (shown.rawName === "@types/node")
+            return { name: "@types/node", version: shown.version };
+        const version = shown.rawName.startsWith("@types/")
+            ? installedVersion(shown.name, cwd) ?? shown.version
+            : shown.version;
+        return { name: shown.name, version };
+    };
+    const versioned = (p) => {
+        const d = display(p);
+        return d.version ? `${d.name}@${d.version}` : d.name;
+    };
+    const displayFields = (p) => {
+        const d = display(p);
+        return { package: d.name, version: d.version };
+    };
+    for (const pkg of imported.values()) {
+        const d = display(pkg);
+        checkedPackages.set(d.name, d.version);
+    }
+    // 2. APIs that don't exist in the installed types.
+    const found = [];
+    // Properties the project assigns onto package objects (`app.db = pool`,
+    // `req.user = decoded` in JS middleware). Those are the user's own
+    // additions, so both the write and every later read are left alone.
+    const assigned = new Set();
+    const memberKey = (located, name) => `${located.ownerLabel}#${name}`;
+    for (const sf of userFiles) {
+        for (const diag of program.getSemanticDiagnostics(sf)) {
+            const code = diag.code;
+            if (!MISSING_EXPORT_CODES.has(code) && !MISSING_MEMBER_CODES.has(code) && !UNKNOWN_OPTION_CODES.has(code))
+                continue;
+            if (diag.start === undefined)
+                continue;
+            const node = nodeAt(sf, diag.start);
+            const located = locate(node, code);
+            if (!located)
+                continue;
+            const name = ts.isIdentifier(node) || ts.isStringLiteralLike(node) || ts.isPrivateIdentifier(node) ? node.text : node.getText(sf);
+            if (isAssignmentTarget(node))
+                assigned.add(memberKey(located, name));
+            found.push({ sf, start: diag.start, message: flatten(diag.messageText), located, name });
+        }
+    }
+    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);
+        const where = versioned(located.owner);
+        let message;
+        if (located.kind === "missing-export") {
+            message = `'${name}' is not exported by ${where}`;
+        }
+        else if (located.kind === "unknown-option") {
+            message = `'${name}' is not a known option of ${located.ownerLabel} (${where})`;
+        }
+        else {
+            message = `'${name}' does not exist on ${located.ownerLabel} (${where})`;
+        }
+        if (suggestion)
+            message += `. Did you mean '${suggestion}'?`;
+        push(sf, start, {
+            kind: located.kind,
+            severity: "error",
+            message,
+            symbol: name,
+            ...displayFields(located.owner),
+            suggestion,
+        });
+    }
+    // 3. APIs that exist but are deprecated in the installed version.
+    for (const sf of userFiles) {
+        if (reportDeprecated) {
+            for (const diag of service.getSuggestionDiagnostics(sf.fileName)) {
+                if (!DEPRECATED_CODES.has(diag.code) || diag.start === undefined)
+                    continue;
+                const node = nodeAt(sf, diag.start);
+                let symbol = checker.getSymbolAtLocation(node);
+                if (symbol && symbol.flags & ts.SymbolFlags.Alias)
+                    symbol = checker.getAliasedSymbol(symbol);
+                const owner = externalOwner(symbol);
+                if (!owner || !symbol)
+                    continue;
+                let tags = symbol.getJsDocTags(checker);
+                const call = node.parent && ts.findAncestor(node.parent, (n) => ts.isCallExpression(n) || ts.isNewExpression(n));
+                if (diag.code === 6387 && call && (ts.isCallExpression(call) || ts.isNewExpression(call))) {
+                    tags = checker.getResolvedSignature(call)?.getJsDocTags() ?? tags;
+                }
+                const note = tags
+                    .find((t) => t.name === "deprecated")
+                    ?.text?.map((p) => p.text)
+                    .join("")
+                    .replace(/\s+/g, " ")
+                    .trim();
+                const name = symbol.getName();
+                push(sf, diag.start, {
+                    kind: "deprecated",
+                    severity: "warning",
+                    message: `'${name}' is deprecated in ${versioned(owner)}${note ? `: ${note}` : ""}`,
+                    symbol: name,
+                    ...displayFields(owner),
+                });
+            }
+        }
+    }
+    // 4. Packages that aren't installed at all.
+    const registryCache = new Map();
+    for (const miss of missingSpecifiers) {
+        let message;
+        if (miss.declared) {
+            message = `'${miss.name}' is listed in package.json but not installed. Run your package manager's install.`;
+        }
+        else {
+            message = `'${miss.name}' is not installed and not listed in package.json`;
+            if (opts.online) {
+                if (!registryCache.has(miss.name))
+                    registryCache.set(miss.name, missingFromRegistry(miss.name));
+                const absent = await registryCache.get(miss.name);
+                if (absent === true)
+                    message = `'${miss.name}' does not exist on npm. It was probably invented; do not install it blindly`;
+                else if (absent === false)
+                    message += `. It exists on npm; check it's the package you meant before installing`;
+            }
+            else {
+                message += `. Check it's a real package before installing`;
+            }
+        }
+        push(miss.sf, miss.node.getStart(miss.sf), {
+            kind: "missing-package",
+            severity: miss.declared ? "warning" : "error",
+            message,
+            symbol: miss.name,
+            package: miss.name,
+        });
+    }
+    issues.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column);
+    return {
+        issues,
+        filesChecked: sources.length,
+        packagesChecked: [...checkedPackages].map(([name, version]) => ({ name, version })).sort((a, b) => a.name.localeCompare(b.name)),
+        unverifiable: [...unverifiable.values()].sort((a, b) => a.package.localeCompare(b.package)),
+    };
+}
+/** Whether `node` is the property name being written in `obj.prop = value` (or `+=`, `??=`, ...). */
+function isAssignmentTarget(node) {
+    const access = node.parent;
+    if (!access || !ts.isPropertyAccessExpression(access) || access.name !== node)
+        return false;
+    const assignment = access.parent;
+    return (!!assignment &&
+        ts.isBinaryExpression(assignment) &&
+        assignment.left === access &&
+        assignment.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+        assignment.operatorToken.kind <= ts.SyntaxKind.LastAssignment);
+}
+/** Whether `specifier` matches a tsconfig `paths` alias. */
+function isAliased(specifier, options) {
+    for (const pattern of Object.keys(options.paths ?? {})) {
+        const star = pattern.indexOf("*");
+        if (star === -1 ? specifier === pattern : specifier.startsWith(pattern.slice(0, star)) && specifier.endsWith(pattern.slice(star + 1))) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Every static module specifier in a file: import/export/require/import(). */
+function moduleSpecifiers(sf) {
+    const out = [];
+    const visit = (node) => {
+        if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteralLike(node.moduleSpecifier)) {
+            // `import type` from an untyped package is still worth tracking; keep all.
+            out.push(node.moduleSpecifier);
+        }
+        else if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference)) {
+            const expr = node.moduleReference.expression;
+            if (ts.isStringLiteralLike(expr))
+                out.push(expr);
+        }
+        else if (ts.isCallExpression(node) && node.arguments.length === 1 && ts.isStringLiteralLike(node.arguments[0])) {
+            const callee = node.expression;
+            const isRequire = ts.isIdentifier(callee) && callee.text === "require";
+            const isDynamicImport = callee.kind === ts.SyntaxKind.ImportKeyword;
+            if (isRequire || isDynamicImport)
+                out.push(node.arguments[0]);
+        }
+        else if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument) && ts.isStringLiteral(node.argument.literal)) {
+            out.push(node.argument.literal);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return out;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { check } from "./analyzer.js";
+import { formatJson, formatPretty } from "./report.js";
+const HELP = `realapi: catch AI-hallucinated imports, methods and options
+
+Usage
+  npx realapi-check [paths...] [options]
+
+Checks your code against the package versions installed in node_modules
+and reports APIs that don't exist there. Works on TypeScript and JavaScript.
+
+Options
+  -p, --project <file>  tsconfig/jsconfig to use (auto-detected by default)
+      --json            Print results as JSON (for CI and AI agents)
+      --online          Check missing packages against the npm registry
+      --no-deprecated   Don't report deprecated APIs
+      --strict          Exit with code 1 on warnings too
+  -h, --help            Show this help
+  -v, --version         Show version
+
+Silence a line with a // realapi-ignore comment on it or on the line above.
+
+Exit codes: 0 clean, 1 problems found, 2 usage or runtime error.`;
+function parseArgs(argv) {
+    const args = { paths: [], project: undefined, json: false, online: false, deprecated: true, strict: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        switch (a) {
+            case "-h":
+            case "--help":
+                console.log(HELP);
+                process.exit(0);
+            case "-v":
+            case "--version": {
+                const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+                console.log(pkg.version);
+                process.exit(0);
+            }
+            case "-p":
+            case "--project":
+                args.project = argv[++i];
+                if (!args.project)
+                    throw new Error(`${a} needs a file path`);
+                break;
+            case "--json":
+                args.json = true;
+                break;
+            case "--online":
+                args.online = true;
+                break;
+            case "--no-deprecated":
+                args.deprecated = false;
+                break;
+            case "--strict":
+                args.strict = true;
+                break;
+            default:
+                if (a.startsWith("-"))
+                    throw new Error(`Unknown option: ${a}`);
+                args.paths.push(a);
+        }
+    }
+    return args;
+}
+async function main() {
+    let args;
+    try {
+        args = parseArgs(process.argv.slice(2));
+    }
+    catch (err) {
+        console.error(`realapi: ${err.message}\nRun 'realapi --help' for usage.`);
+        process.exit(2);
+    }
+    try {
+        const result = await check({
+            paths: args.paths,
+            project: args.project,
+            deprecated: args.deprecated,
+            online: args.online,
+        });
+        console.log(args.json ? formatJson(result) : formatPretty(result));
+        const failing = result.issues.some((i) => i.severity === "error" || args.strict);
+        // exitCode rather than exit(): piped stdout is async on some platforms and
+        // exiting immediately can truncate large --json output.
+        process.exitCode = failing ? 1 : 0;
+    }
+    catch (err) {
+        console.error(`realapi: ${err.message}`);
+        process.exitCode = 2;
+    }
+}
+main();

package/dist/files.d.ts

@@ -0,0 +1,11 @@
+export declare function isDeclarationFile(file: string): boolean;
+/** Absolute, forward-slash path, matching how TypeScript names source files. */
+export declare function normalize(file: string): string;
+/** Source files under the given paths (files or directories). */
+export declare function collectSourceFiles(cwd: string, paths: string[]): string[];
+/**
+ * Project `.d.ts` files anywhere under cwd. These carry module augmentation
+ * (`declare module "express" { ... }`) and env typings (`vite-env.d.ts`), so
+ * they must be part of the program even when only `src/` is being checked.
+ */
+export declare function collectProjectDeclarations(cwd: string): string[];

package/dist/files.js

@@ -0,0 +1,78 @@
+import fs from "node:fs";
+import path from "node:path";
+const SOURCE_EXT = /\.(?:[cm]?[jt]s|[jt]sx)$/;
+const DECLARATION = /\.d\.[cm]?ts$/;
+const IGNORED_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    "out",
+    "coverage",
+    ".next",
+    ".nuxt",
+    ".svelte-kit",
+    ".output",
+    ".turbo",
+    ".vercel",
+    ".cache",
+    ".yarn",
+]);
+export function isDeclarationFile(file) {
+    return DECLARATION.test(file);
+}
+/** Absolute, forward-slash path, matching how TypeScript names source files. */
+export function normalize(file) {
+    return path.resolve(file).replace(/\\/g, "/");
+}
+function walk(dir, out, filter) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (!IGNORED_DIRS.has(entry.name))
+                walk(full, out, filter);
+        }
+        else if (entry.isFile() && filter(entry.name)) {
+            out.add(normalize(full));
+        }
+    }
+}
+function isSource(name) {
+    return SOURCE_EXT.test(name) && !/\.min\.[cm]?js$/.test(name);
+}
+/** Source files under the given paths (files or directories). */
+export function collectSourceFiles(cwd, paths) {
+    const out = new Set();
+    for (const p of paths) {
+        const full = path.resolve(cwd, p);
+        let stat;
+        try {
+            stat = fs.statSync(full);
+        }
+        catch {
+            throw new Error(`Path not found: ${p}`);
+        }
+        if (stat.isDirectory())
+            walk(full, out, isSource);
+        else
+            out.add(normalize(full));
+    }
+    return [...out];
+}
+/**
+ * Project `.d.ts` files anywhere under cwd. These carry module augmentation
+ * (`declare module "express" { ... }`) and env typings (`vite-env.d.ts`), so
+ * they must be part of the program even when only `src/` is being checked.
+ */
+export function collectProjectDeclarations(cwd) {
+    const out = new Set();
+    walk(cwd, out, isDeclarationFile);
+    return [...out];
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { check } from "./analyzer.js";
+export { formatJson, formatPretty } from "./report.js";
+export type { CheckOptions, CheckResult, Issue, IssueKind, Severity, Unverifiable } from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { check } from "./analyzer.js";
+export { formatJson, formatPretty } from "./report.js";

package/dist/packages.d.ts

@@ -0,0 +1,37 @@
+export declare function isBuiltin(specifier: string): boolean;
+/**
+ * Package name for a bare specifier, or undefined when the specifier is not a
+ * plain npm package reference (relative paths, `#imports`, `@/` or `~/`
+ * aliases, `virtual:`-style schemes).
+ */
+export declare function packageNameOf(specifier: string): string | undefined;
+/** `@types/foo` → `foo`, `@types/babel__core` → `@babel/core`, `@types/node` → `node`. */
+export declare function fromTypesPackage(name: string): string;
+export interface PackageInfo {
+    /** User-facing name: `@types/lodash` is reported as `lodash`. */
+    name: string;
+    version?: string;
+    /** Name as published, e.g. `@types/lodash`. */
+    rawName: string;
+    /** Package directory, forward slashes. */
+    root: string;
+    /** Names of this package's own dependencies. */
+    dependencies: string[];
+}
+/**
+ * The package a node_modules file belongs to. Uses the last `node_modules/`
+ * segment so pnpm's `.pnpm/pkg@1.0.0/node_modules/pkg/...` layout works.
+ */
+export declare function packageOfFile(fileName: string): PackageInfo | undefined;
+/** Version of `name` installed in a node_modules directory visible from `fromDir`. */
+export declare function installedVersion(name: string, fromDir: string): string | undefined;
+/** Whether `name` is installed in a node_modules directory visible from `fromDir`. */
+export declare function isInstalled(name: string, fromDir: string): boolean;
+/** Yarn Plug'n'Play has no node_modules, so on-disk presence can't be checked. */
+export declare function usesPnp(cwd: string): boolean;
+/** Every dependency name declared in the nearest package.json. */
+export declare function declaredDependencies(cwd: string): Set<string>;
+/** Names of every installed `@types/*` package visible from cwd, as `types` entries. */
+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>;

package/dist/packages.js

@@ -0,0 +1,175 @@
+import fs from "node:fs";
+import path from "node:path";
+import { builtinModules } from "node:module";
+const BUILTINS = new Set(builtinModules);
+export function isBuiltin(specifier) {
+    if (specifier.startsWith("node:"))
+        return true;
+    return BUILTINS.has(specifier) || BUILTINS.has(specifier.split("/")[0]);
+}
+/**
+ * Package name for a bare specifier, or undefined when the specifier is not a
+ * plain npm package reference (relative paths, `#imports`, `@/` or `~/`
+ * aliases, `virtual:`-style schemes).
+ */
+export function packageNameOf(specifier) {
+    if (specifier.startsWith("node:"))
+        return "node";
+    if (!specifier || specifier.startsWith(".") || specifier.startsWith("/"))
+        return undefined;
+    if (specifier.startsWith("#") || specifier.startsWith("~") || specifier.startsWith("@/"))
+        return undefined;
+    if (/^[a-zA-Z][\w+.-]*:/.test(specifier))
+        return undefined;
+    const parts = specifier.split("/");
+    if (specifier.startsWith("@")) {
+        if (parts.length < 2 || !parts[1])
+            return undefined;
+        return `${parts[0]}/${parts[1]}`;
+    }
+    return parts[0];
+}
+/** `@types/foo` → `foo`, `@types/babel__core` → `@babel/core`, `@types/node` → `node`. */
+export function fromTypesPackage(name) {
+    if (!name.startsWith("@types/"))
+        return name;
+    const bare = name.slice("@types/".length);
+    return bare.includes("__") ? `@${bare.replace("__", "/")}` : bare;
+}
+const infoCache = new Map();
+/**
+ * The package a node_modules file belongs to. Uses the last `node_modules/`
+ * segment so pnpm's `.pnpm/pkg@1.0.0/node_modules/pkg/...` layout works.
+ */
+export function packageOfFile(fileName) {
+    const marker = "/node_modules/";
+    const idx = fileName.lastIndexOf(marker);
+    if (idx === -1)
+        return undefined;
+    const rest = fileName.slice(idx + marker.length).split("/");
+    const rawName = rest[0].startsWith("@") ? `${rest[0]}/${rest[1]}` : rest[0];
+    const root = fileName.slice(0, idx + marker.length) + rawName;
+    if (infoCache.has(root))
+        return infoCache.get(root);
+    let info = { name: fromTypesPackage(rawName), rawName, root, dependencies: [] };
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+        const published = pkg.name ?? rawName;
+        info = {
+            name: fromTypesPackage(published),
+            version: pkg.version,
+            rawName: published,
+            root,
+            dependencies: Object.keys({ ...pkg.dependencies, ...pkg.peerDependencies }),
+        };
+    }
+    catch {
+        // Keep the name derived from the path.
+    }
+    infoCache.set(root, info);
+    return info;
+}
+/** Version of `name` installed in a node_modules directory visible from `fromDir`. */
+export function installedVersion(name, fromDir) {
+    let dir = path.resolve(fromDir);
+    for (;;) {
+        try {
+            return JSON.parse(fs.readFileSync(path.join(dir, "node_modules", name, "package.json"), "utf8")).version;
+        }
+        catch {
+            // Keep looking upward.
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/** Whether `name` is installed in a node_modules directory visible from `fromDir`. */
+export function isInstalled(name, fromDir) {
+    let dir = path.resolve(fromDir);
+    for (;;) {
+        if (fs.existsSync(path.join(dir, "node_modules", name)))
+            return true;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return false;
+        dir = parent;
+    }
+}
+/** Yarn Plug'n'Play has no node_modules, so on-disk presence can't be checked. */
+export function usesPnp(cwd) {
+    let dir = path.resolve(cwd);
+    for (;;) {
+        if (fs.existsSync(path.join(dir, ".pnp.cjs")) || fs.existsSync(path.join(dir, ".pnp.js")))
+            return true;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return false;
+        dir = parent;
+    }
+}
+/** Every dependency name declared in the nearest package.json. */
+export function declaredDependencies(cwd) {
+    const names = new Set();
+    let dir = path.resolve(cwd);
+    for (;;) {
+        const file = path.join(dir, "package.json");
+        if (fs.existsSync(file)) {
+            try {
+                const pkg = JSON.parse(fs.readFileSync(file, "utf8"));
+                for (const field of ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]) {
+                    for (const name of Object.keys(pkg[field] ?? {}))
+                        names.add(name);
+                }
+            }
+            catch {
+                // Ignore unreadable package.json.
+            }
+            return names;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return names;
+        dir = parent;
+    }
+}
+/** Names of every installed `@types/*` package visible from cwd, as `types` entries. */
+export function installedTypesPackages(cwd) {
+    const names = new Set();
+    let dir = path.resolve(cwd);
+    for (;;) {
+        const typesDir = path.join(dir, "node_modules", "@types");
+        try {
+            for (const entry of fs.readdirSync(typesDir)) {
+                if (!entry.startsWith("."))
+                    names.add(entry);
+            }
+        }
+        catch {
+            // No @types here.
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return [...names];
+}
+/** Returns true when the npm registry has no package with this name. */
+export async function missingFromRegistry(name) {
+    try {
+        const res = await fetch(`https://registry.npmjs.org/${name.replace("/", "%2F")}`, {
+            method: "HEAD",
+            signal: AbortSignal.timeout(8000),
+        });
+        if (res.status === 404)
+            return true;
+        if (res.ok)
+            return false;
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/report.d.ts

@@ -0,0 +1,3 @@
+import type { CheckResult } from "./types.js";
+export declare function formatPretty(result: CheckResult): string;
+export declare function formatJson(result: CheckResult): string;

package/dist/report.js

@@ -0,0 +1,46 @@
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : s);
+const red = paint("31");
+const yellow = paint("33");
+const green = paint("32");
+const dim = paint("2");
+const bold = paint("1");
+const underline = paint("4");
+const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+export function formatPretty(result) {
+    const out = [];
+    let currentFile = "";
+    for (const issue of result.issues) {
+        if (issue.file !== currentFile) {
+            if (currentFile)
+                out.push("");
+            out.push(underline(issue.file));
+            currentFile = issue.file;
+        }
+        const pos = dim(`${issue.line}:${issue.column}`.padEnd(8));
+        const sev = issue.severity === "error" ? red("error  ") : yellow("warning");
+        out.push(`  ${pos} ${sev}  ${issue.message}  ${dim(issue.kind)}`);
+        if (issue.sourceLine)
+            out.push(`  ${" ".repeat(8)}          ${dim(issue.sourceLine)}`);
+    }
+    const errors = result.issues.filter((i) => i.severity === "error").length;
+    const warnings = result.issues.length - errors;
+    if (result.issues.length)
+        out.push("");
+    const scope = dim(`checked ${plural(result.filesChecked, "file")} against ${plural(result.packagesChecked.length, "installed package")}`);
+    if (result.issues.length === 0) {
+        out.push(`${green("✔")} ${bold("No hallucinated APIs found")} ${scope}`);
+    }
+    else {
+        const color = errors ? red : yellow;
+        out.push(`${color("✖")} ${bold(plural(result.issues.length, "problem"))} (${plural(errors, "error")}, ${plural(warnings, "warning")}) ${scope}`);
+    }
+    if (result.unverifiable.length) {
+        const names = result.unverifiable.map((u) => (u.reason === "no-node-types" ? "node built-ins (install @types/node)" : u.package));
+        out.push(yellow(`⚠ Not verified, no type definitions: ${names.join(", ")}`));
+    }
+    return out.join("\n");
+}
+export function formatJson(result) {
+    return JSON.stringify(result, null, 2);
+}

package/dist/types.d.ts

@@ -0,0 +1,57 @@
+export type Severity = "error" | "warning";
+export type IssueKind = 
+/** `import { x } from "pkg"` where the installed version doesn't export `x`. */
+"missing-export"
+/** `thing.method()` where the package's type has no such member. */
+ | "missing-member"
+/** `fn({ option: 1 })` where the package's options type has no such key. */
+ | "unknown-option"
+/** A bare import of a package that isn't installed. */
+ | "missing-package"
+/** The API exists but the installed version marks it `@deprecated`. */
+ | "deprecated";
+export interface Issue {
+    kind: IssueKind;
+    severity: Severity;
+    /** Path relative to cwd, always with forward slashes. */
+    file: string;
+    line: number;
+    column: number;
+    message: string;
+    /** The name the code used, e.g. `emial`. */
+    symbol?: string;
+    /** Package the API belongs to, e.g. `zod` or `node` for built-ins. */
+    package?: string;
+    version?: string;
+    /** Closest real name, when one exists. */
+    suggestion?: string;
+    /** The trimmed source line, for display. */
+    sourceLine: string;
+}
+export interface Unverifiable {
+    package: string;
+    reason: "no-types" | "no-node-types";
+}
+export interface CheckResult {
+    issues: Issue[];
+    filesChecked: number;
+    /** Installed packages whose types were used to verify imports. */
+    packagesChecked: {
+        name: string;
+        version?: string;
+    }[];
+    /** Imported packages that could not be verified because they ship no types. */
+    unverifiable: Unverifiable[];
+}
+export interface CheckOptions {
+    /** Project root. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Files or directories to check, relative to cwd. Defaults to `["."]`. */
+    paths?: string[];
+    /** Path to a tsconfig/jsconfig. Auto-detected when omitted. */
+    project?: string;
+    /** Report `@deprecated` APIs as warnings. Defaults to true. */
+    deprecated?: boolean;
+    /** Look up missing packages on the npm registry. Defaults to false. */
+    online?: boolean;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "realapi-check",
+  "version": "0.1.0",
+  "description": "Catch AI-hallucinated imports, methods and options that don't exist in the package versions you actually have installed.",
+  "type": "module",
+  "bin": {
+    "realapi-check": "dist/cli.js",
+    "realapi": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && vitest run",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "ai",
+    "hallucination",
+    "llm",
+    "lint",
+    "cli",
+    "typescript",
+    "api",
+    "copilot",
+    "claude",
+    "cursor",
+    "static-analysis"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "author": "Naveen Elango",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/navin017/realAPI.git"
+  },
+  "homepage": "https://github.com/navin017/realAPI#readme",
+  "bugs": {
+    "url": "https://github.com/navin017/realAPI/issues"
+  },
+  "dependencies": {
+    "typescript": "~6.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "vitest": "^3.2.0"
+  }
+}