@sdk-usage/core 0.2.0-next.1794009490550.b76492b → 0.2.0

package/dist/index.cjs

@@ -0,0 +1,415 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+let node_fs_promises = require("node:fs/promises");
+let node_path = require("node:path");
+let node_fs = require("node:fs");
+let node_module = require("node:module");
+let _open_vanilla_visitor = require("@open-vanilla/visitor");
+let _swc_core = require("@swc/core");
+let node_child_process = require("node:child_process");
+let node_stream = require("node:stream");
+let node_util = require("node:util");
+
+// src/entities/item/create-item.ts
+/**
+* Creates an SDK usage item.
+*
+* @example
+* 	createItem({ ... });
+*
+* @param input - Factory variables.
+* @param input.name - Name.
+* @param input.type - Component type.
+* @param input.module - Source module.
+* @param input.version - Module version.
+* @param input.location - Location.
+* @param input.input - Parameter list and metadata describing the way it's passed.
+* @returns An SDK usage item with its source location and module version.
+*/
+const createItem = ({ name, input, location, module, type, version }) => {
+	return {
+		name,
+		createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+		input: {
+			metadata: { withSpreading: input?.metadata.withSpreading ?? false },
+			data: input?.data ?? {}
+		},
+		location,
+		module,
+		type,
+		version
+	};
+};
+
+// src/entities/item/create-locator.ts
+/**
+* Creates a locator for SDK usages in a source file.
+*
+* @param input - Source file and its package metadata.
+* @param input.code - Source text.
+* @param input.file - Absolute source file path.
+* @param input.link - Repository link.
+* @param input.module - Package name.
+* @param input.path - Root path that the reported file is relative to.
+* @returns A function that reports a usage's source location and package metadata.
+*/
+const createLocator = ({ code, file, link, module, path }) => {
+	const source = Buffer.from(code);
+	const lineStarts = [0];
+	const relativeFile = `./${(0, node_path.relative)(path, file)}`;
+	for (let index = source.indexOf("\n"); index !== -1; index = source.indexOf("\n", index + 1)) lineStarts.push(index + 1);
+	return (offset) => {
+		const line = Math.max(1, lineStarts.findLastIndex((lineStart) => {
+			return lineStart <= offset;
+		}) + 1);
+		return {
+			column: source.toString("utf8", lineStarts[line - 1], offset).length,
+			file: relativeFile,
+			line,
+			link,
+			module
+		};
+	};
+};
+
+// src/helpers.ts
+const require$1 = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
+const resolvePackageJson = (fromPath) => {
+	const filepath = (0, node_path.join)(fromPath, "./package.json");
+	if ((0, node_fs.existsSync)(filepath)) return filepath;
+	return resolvePackageJson((0, node_path.join)(fromPath, "../"));
+};
+
+// src/modules/parser/parse.ts
+/**
+* Collects SDK usages from a source file using the enabled plugins.
+*
+* @param code - Source text to parse.
+* @param options - Parse options.
+* @param options.file - Source file path, used in parse errors.
+* @param options.plugins - Enabled plugins.
+* @returns An iterator of collected SDK usages with their source positions.
+*/
+const parse = async (code, { file, plugins }) => {
+	let ast;
+	try {
+		ast = await (0, _swc_core.parse)(code, {
+			syntax: "typescript",
+			tsx: true
+		});
+	} catch (error) {
+		throw new Error(`Failed to parse source file: ${file}`, { cause: error });
+	}
+	const context = { imports: /* @__PURE__ */ new Map() };
+	(0, _open_vanilla_visitor.visit)(ast, { ImportDeclaration(node) {
+		for (const specifier of node.specifiers) {
+			const alias = specifier.local.value;
+			const name = "imported" in specifier && Boolean(specifier.imported) ? specifier.imported.value : alias;
+			const typeOnly = node.typeOnly || "isTypeOnly" in specifier && specifier.isTypeOnly;
+			context.imports.set(alias, {
+				name,
+				alias,
+				bindingContext: getBindingContext(specifier.local),
+				module: node.source.value,
+				typeOnly
+			});
+		}
+	} });
+	(0, _open_vanilla_visitor.visit)(ast, { VariableDeclarator(node) {
+		const imported = getDeclaratorImport(node, context.imports);
+		if (imported) addImportedBindings(node.id, imported, context.imports);
+	} });
+	const parentNodes = getParentNodes(ast);
+	const getParentNode = (node) => {
+		return parentNodes.get(node);
+	};
+	const visitorsByType = Map.groupBy(plugins.flatMap((plugin) => {
+		return Object.entries(plugin({
+			...context,
+			getJSXAttributeValue,
+			getParentNode
+		}));
+	}), ([type]) => {
+		return type;
+	});
+	return getNodes(ast).flatMap((node) => {
+		return (visitorsByType.get(String(node.type)) ?? []).map(([, visitor]) => {
+			const item = visitor(node);
+			if (item) item.offset -= 1;
+			return item;
+		});
+	}).filter((item) => {
+		return item !== void 0;
+	});
+};
+const getNodes = (ast) => {
+	const pending = [ast];
+	return Iterator.from({ next() {
+		while (pending.length > 0) {
+			const value = pending.pop();
+			if (!isRecord(value)) continue;
+			const children = Object.values(value);
+			for (let index = children.length - 1; index >= 0; index -= 1) pending.push(children[index]);
+			if (!Array.isArray(value)) return {
+				done: false,
+				value
+			};
+		}
+		return {
+			done: true,
+			value: void 0
+		};
+	} });
+};
+const getParentNodes = (ast) => {
+	const parentNodes = /* @__PURE__ */ new WeakMap();
+	const pending = [{
+		parent: void 0,
+		value: ast
+	}];
+	while (pending.length > 0) {
+		const current = pending.pop();
+		if (!current) continue;
+		const { parent, value } = current;
+		if (Array.isArray(value)) {
+			for (const child of value) pending.push({
+				parent,
+				value: child
+			});
+			continue;
+		}
+		if (!isRecord(value)) continue;
+		if (parent) parentNodes.set(value, parent);
+		for (const child of Object.values(value)) pending.push({
+			parent: value,
+			value: child
+		});
+	}
+	return parentNodes;
+};
+const isRecord = (value) => {
+	return typeof value === "object" && value !== null;
+};
+const getBindingContext = (identifier) => {
+	return "ctxt" in identifier && typeof identifier.ctxt === "number" ? identifier.ctxt : void 0;
+};
+const getDeclaratorImport = (node, imports) => {
+	const initializer = node.init;
+	if (initializer?.type !== "Identifier") return;
+	const imported = imports.get(initializer.value);
+	return imported?.bindingContext !== void 0 && imported.bindingContext === getBindingContext(initializer) ? imported : void 0;
+};
+const addImportedBindings = (pattern, imported, imports) => {
+	if (pattern.type === "Identifier") {
+		const { value: alias } = pattern;
+		const bindingContext = getBindingContext(pattern);
+		const existing = imports.get(alias);
+		if (bindingContext === void 0 || existing && existing.bindingContext !== bindingContext) return;
+		imports.set(alias, {
+			...imported,
+			alias,
+			bindingContext
+		});
+		return;
+	}
+	if (pattern.type !== "ObjectPattern") return;
+	for (const property of pattern.properties) {
+		if (property.type === "KeyValuePatternProperty") {
+			if (property.key.type === "Identifier" || property.key.type === "StringLiteral") addImportedBindings(property.value, {
+				...imported,
+				name: property.key.value
+			}, imports);
+			continue;
+		}
+		if (property.type === "AssignmentPatternProperty") addImportedBindings(property.key, {
+			...imported,
+			name: property.key.value
+		}, imports);
+	}
+};
+const getJSXAttributeValue = (node) => {
+	if (!node) return true;
+	if (node.type === "BigIntLiteral" || node.type === "BooleanLiteral" || node.type === "JSXText" || node.type === "NumericLiteral" || node.type === "StringLiteral") return node.value;
+	if (node.type === "JSXExpressionContainer") return getJSXAttributeValue(node.expression);
+	if (node.type === "NullLiteral") return;
+	return createUnknownToken(node.type);
+};
+/**
+* Creates a placeholder for an unsupported source expression.
+*
+* @example
+* 	createUnknownToken("VariableDeclaration");
+*
+* @param syntax - SWC syntax node name.
+* @returns A placeholder identifying the unsupported expression.
+*/
+const createUnknownToken = (syntax) => {
+	return {
+		syntax,
+		type: "unsupported-syntax"
+	};
+};
+
+// src/modules/scanner/scan.ts
+const execFileAsync = (0, node_util.promisify)(node_child_process.execFile);
+const DEFAULT_EXCLUDED_FOLDERS = [
+	".git",
+	"node_modules",
+	"dist",
+	"out"
+];
+const DEFAULT_INCLUDED_FILES = ["**/!(test|*.test|stories|*.stories).?(m){j,t}s?(x)"];
+/**
+* Finds matching source files in the package tree at `path`.
+*
+* @param path - Root directory to scan.
+* @param signal - Cancels the scan.
+* @param options - File and folder filters.
+* @returns A backpressure-aware stream of matching source files and their package metadata.
+*/
+const scan = (path, signal, options) => {
+	const excludedFolders = new Set(options.excludeFolders ?? DEFAULT_EXCLUDED_FOLDERS);
+	const includedFiles = options.includeFiles ?? DEFAULT_INCLUDED_FILES;
+	const isIncluded = (file, project) => {
+		const relativeFile = (0, node_path.relative)(project.folder, file).replaceAll(node_path.sep, "/");
+		return includedFiles.some((pattern) => {
+			return (0, node_path.matchesGlob)(relativeFile, pattern);
+		});
+	};
+	const scanDirectory = (folder, parentProject) => {
+		return node_stream.Readable.from([folder]).flatMap(async () => {
+			const project = await getProject(folder) ?? parentProject;
+			return node_stream.Readable.from(await (0, node_fs_promises.opendir)(folder)).flatMap((entry) => {
+				const file = (0, node_path.join)(folder, entry.name);
+				if (entry.isDirectory() && excludedFolders.has(entry.name)) return [];
+				if (entry.isDirectory()) return scanDirectory(file, project);
+				const isSourceFile = entry.isFile() || entry.isSymbolicLink();
+				if (!project || !isSourceFile || !isIncluded(file, project)) return [];
+				return [{
+					...project,
+					file
+				}];
+			}, { signal });
+		});
+	};
+	return scanDirectory(path);
+};
+const getProject = async (folder) => {
+	try {
+		const content = await (0, node_fs_promises.readFile)((0, node_path.join)(folder, "package.json"), "utf8");
+		return {
+			metadata: JSON.parse(content),
+			folder,
+			link: await getRepositoryUrl(folder)
+		};
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return;
+		throw error;
+	}
+};
+const getRepositoryUrl = async (folder) => {
+	try {
+		const { stdout } = await execFileAsync("git", [
+			"config",
+			"--get",
+			"remote.origin.url"
+		], { cwd: folder });
+		return stdout.trim();
+	} catch {
+		return "";
+	}
+};
+
+// src/create-instance.ts
+/**
+* Creates an analyzer for the package tree at `path`.
+*
+* @param path - Root directory to scan.
+* @param options - Optional file filters, module filters, and parser plugins.
+* @returns An analyzer that collects matching SDK usages.
+*/
+const createInstance = (path, options) => {
+	const { includeModules = [], plugins = [], resolveInstalledVersions = false } = options;
+	const getFileItems = async ({ metadata, file, link }, signal) => {
+		const code = await (0, node_fs_promises.readFile)(file, {
+			encoding: "utf8",
+			signal
+		});
+		const items = await parse(code, {
+			file,
+			plugins
+		});
+		const locate = createLocator({
+			code,
+			file,
+			link,
+			module: metadata.name,
+			path
+		});
+		const dependencies = {
+			...metadata.devDependencies,
+			...metadata.optionalDependencies,
+			...metadata.dependencies
+		};
+		return items.filter(({ module }) => {
+			return includeModules.length === 0 || includeModules.includes(module);
+		}).map((item) => {
+			const version = (resolveInstalledVersions ? getInstalledVersion(item.module, file) : void 0) ?? dependencies[item.module] ?? "";
+			return createItem({
+				...item,
+				location: locate(item.offset),
+				version
+			});
+		});
+	};
+	return { 
+	/**
+	* Collects matching SDK usages from the package tree. Stopping iteration cancels pending
+	* scans; scans already in progress may finish.
+	*
+	* @returns An async iterable of matching SDK usages with their source locations and
+	*   versions.
+	*/
+getItems() {
+		const controller = new AbortController();
+		const { signal } = controller;
+		const iterator = scan(path, signal, options).flatMap(async (file) => {
+			return getFileItems(file, signal);
+		}).iterator();
+		return {
+			next: iterator.next.bind(iterator),
+			async return() {
+				controller.abort();
+				await iterator.return?.();
+				return {
+					done: true,
+					value: void 0
+				};
+			},
+			[Symbol.asyncIterator]() {
+				return this;
+			}
+		};
+	} };
+};
+const getInstalledVersion = (module, file) => {
+	try {
+		const { version } = require$1(resolvePackageJson(require$1.resolve(module, { paths: [file] })));
+		return version;
+	} catch {
+		return;
+	}
+};
+
+// src/modules/plugin/create-plugin.ts
+/**
+* Returns a plugin definition unchanged for convenient type inference.
+*
+* @param input - Plugin implementation.
+* @returns The supplied plugin implementation.
+*/
+const createPlugin = (input) => {
+	return input;
+};
+
+exports.createInstance = createInstance;
+exports.createPlugin = createPlugin;

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+import { CallExpression, Identifier, ImportDeclaration, JSXAttrValue as AstJSXAttrValue, JSXOpeningElement, NewExpression, OptionalChainingExpression, TaggedTemplateExpression, TsExpressionWithTypeArguments, TsType, VariableDeclarator } from "@swc/core";
+type AstNode = Record<string, unknown>;
+type AstNodes = {
+  CallExpression: CallExpression;
+  Identifier: Identifier;
+  ImportDeclaration: ImportDeclaration;
+  JSXOpeningElement: JSXOpeningElement;
+  NewExpression: NewExpression;
+  OptionalChainingExpression: OptionalChainingExpression;
+  TaggedTemplateExpression: TaggedTemplateExpression;
+  TsExpressionWithTypeArguments: TsExpressionWithTypeArguments;
+  TsImportType: Extract<TsType, {
+    type: "TsImportType";
+  }>;
+  TsTypeQuery: Extract<TsType, {
+    type: "TsTypeQuery";
+  }>;
+  TsTypeReference: Extract<TsType, {
+    type: "TsTypeReference";
+  }>;
+  VariableDeclarator: VariableDeclarator;
+};
+/** Import entity to model an import statement. */
+type Import = {
+  name: string;
+  alias: string;
+  /** SWC context used to distinguish this import from shadowing local bindings. */
+  bindingContext: number | undefined;
+  module: string;
+  typeOnly: boolean;
+};
+/** Package entity to model `package.json` metadata. */
+type Package = {
+  name: string;
+  description: string;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  version: string;
+};
+type Primitive = bigint | boolean | null | number | string | undefined;
+/** Placeholder for a JSX expression whose source value is not statically known. */
+type UnsupportedSyntaxToken = {
+  syntax: string;
+  type: "unsupported-syntax";
+};
+type Location = {
+  column: number;
+  file: string;
+  line: number;
+  link: string;
+  module: string;
+};
+type Item = {
+  name: string;
+  createdAt: string;
+  input: {
+    metadata: {
+      withSpreading: boolean;
+    };
+    data: Record<string, unknown>;
+  };
+  location: Location;
+  module: Package["name"];
+  type: string;
+  version: Package["version"];
+};
+type ItemDTO = Partial<Pick<Item, "input">> & Pick<Item, "module" | "name" | "type"> & {
+  offset: number;
+};
+/**
+ * Returns a plugin definition unchanged for convenient type inference.
+ *
+ * @param input - Plugin implementation.
+ * @returns The supplied plugin implementation.
+ */
+export declare const createPlugin: (input: Plugin) => Plugin;
+type Plugin = (input: {
+  getJSXAttributeValue: (node: AstJSXAttrValue | undefined) => Primitive | UnsupportedSyntaxToken;
+  getParentNode: (node: object) => AstNode | undefined;
+  imports: Map<Import["alias"], Import>;
+}) => { [Key in keyof AstNodes]?: (node: AstNodes[Key]) => ItemDTO | undefined; };
+type ScanOptions = {
+  /** A list of folders to ignore. */
+  excludeFolders?: string[];
+  /**
+   * Include patterns using `node:path.matchesGlob` semantics. Dot-prefixed path segments must be
+   * matched explicitly; leading `!` is not negation.
+   */
+  includeFiles?: string[];
+};
+type Options = Partial<ScanOptions & {
+  /** Only analyze components imported from the specified module list. */
+  includeModules: string[];
+  /** A list of plugins to enable. */
+  plugins: Plugin[];
+  /**
+   * Attempt to resolve installed versions of modules. If false or not possible, the specified
+   * version from the package.json will be used.
+   *
+   * @default false
+   */
+  resolveInstalledVersions: boolean;
+}>;
+/**
+ * Creates an analyzer for the package tree at `path`.
+ *
+ * @param path - Root directory to scan.
+ * @param options - Optional file filters, module filters, and parser plugins.
+ * @returns An analyzer that collects matching SDK usages.
+ */
+export declare const createInstance: (path: string, options: Options) => {
+  /**
+   * Collects matching SDK usages from the package tree. Stopping iteration cancels pending
+   * scans; scans already in progress may finish.
+   *
+   * @returns An async iterable of matching SDK usages with their source locations and
+   *   versions.
+   */
+  getItems(): AsyncIterable<Item>;
+};
+export type { Plugin };

package/dist/index.mjs

@@ -0,0 +1,413 @@
+import { opendir, readFile } from "node:fs/promises";
+import { join, matchesGlob, relative, sep } from "node:path";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { visit } from "@open-vanilla/visitor";
+import { parse } from "@swc/core";
+import { execFile } from "node:child_process";
+import { Readable } from "node:stream";
+import { promisify } from "node:util";
+
+// src/entities/item/create-item.ts
+/**
+* Creates an SDK usage item.
+*
+* @example
+* 	createItem({ ... });
+*
+* @param input - Factory variables.
+* @param input.name - Name.
+* @param input.type - Component type.
+* @param input.module - Source module.
+* @param input.version - Module version.
+* @param input.location - Location.
+* @param input.input - Parameter list and metadata describing the way it's passed.
+* @returns An SDK usage item with its source location and module version.
+*/
+const createItem = ({ name, input, location, module, type, version }) => {
+	return {
+		name,
+		createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+		input: {
+			metadata: { withSpreading: input?.metadata.withSpreading ?? false },
+			data: input?.data ?? {}
+		},
+		location,
+		module,
+		type,
+		version
+	};
+};
+
+// src/entities/item/create-locator.ts
+/**
+* Creates a locator for SDK usages in a source file.
+*
+* @param input - Source file and its package metadata.
+* @param input.code - Source text.
+* @param input.file - Absolute source file path.
+* @param input.link - Repository link.
+* @param input.module - Package name.
+* @param input.path - Root path that the reported file is relative to.
+* @returns A function that reports a usage's source location and package metadata.
+*/
+const createLocator = ({ code, file, link, module, path }) => {
+	const source = Buffer.from(code);
+	const lineStarts = [0];
+	const relativeFile = `./${relative(path, file)}`;
+	for (let index = source.indexOf("\n"); index !== -1; index = source.indexOf("\n", index + 1)) lineStarts.push(index + 1);
+	return (offset) => {
+		const line = Math.max(1, lineStarts.findLastIndex((lineStart) => {
+			return lineStart <= offset;
+		}) + 1);
+		return {
+			column: source.toString("utf8", lineStarts[line - 1], offset).length,
+			file: relativeFile,
+			line,
+			link,
+			module
+		};
+	};
+};
+
+// src/helpers.ts
+const require = createRequire(import.meta.url);
+const resolvePackageJson = (fromPath) => {
+	const filepath = join(fromPath, "./package.json");
+	if (existsSync(filepath)) return filepath;
+	return resolvePackageJson(join(fromPath, "../"));
+};
+
+// src/modules/parser/parse.ts
+/**
+* Collects SDK usages from a source file using the enabled plugins.
+*
+* @param code - Source text to parse.
+* @param options - Parse options.
+* @param options.file - Source file path, used in parse errors.
+* @param options.plugins - Enabled plugins.
+* @returns An iterator of collected SDK usages with their source positions.
+*/
+const parse$1 = async (code, { file, plugins }) => {
+	let ast;
+	try {
+		ast = await parse(code, {
+			syntax: "typescript",
+			tsx: true
+		});
+	} catch (error) {
+		throw new Error(`Failed to parse source file: ${file}`, { cause: error });
+	}
+	const context = { imports: /* @__PURE__ */ new Map() };
+	visit(ast, { ImportDeclaration(node) {
+		for (const specifier of node.specifiers) {
+			const alias = specifier.local.value;
+			const name = "imported" in specifier && Boolean(specifier.imported) ? specifier.imported.value : alias;
+			const typeOnly = node.typeOnly || "isTypeOnly" in specifier && specifier.isTypeOnly;
+			context.imports.set(alias, {
+				name,
+				alias,
+				bindingContext: getBindingContext(specifier.local),
+				module: node.source.value,
+				typeOnly
+			});
+		}
+	} });
+	visit(ast, { VariableDeclarator(node) {
+		const imported = getDeclaratorImport(node, context.imports);
+		if (imported) addImportedBindings(node.id, imported, context.imports);
+	} });
+	const parentNodes = getParentNodes(ast);
+	const getParentNode = (node) => {
+		return parentNodes.get(node);
+	};
+	const visitorsByType = Map.groupBy(plugins.flatMap((plugin) => {
+		return Object.entries(plugin({
+			...context,
+			getJSXAttributeValue,
+			getParentNode
+		}));
+	}), ([type]) => {
+		return type;
+	});
+	return getNodes(ast).flatMap((node) => {
+		return (visitorsByType.get(String(node.type)) ?? []).map(([, visitor]) => {
+			const item = visitor(node);
+			if (item) item.offset -= 1;
+			return item;
+		});
+	}).filter((item) => {
+		return item !== void 0;
+	});
+};
+const getNodes = (ast) => {
+	const pending = [ast];
+	return Iterator.from({ next() {
+		while (pending.length > 0) {
+			const value = pending.pop();
+			if (!isRecord(value)) continue;
+			const children = Object.values(value);
+			for (let index = children.length - 1; index >= 0; index -= 1) pending.push(children[index]);
+			if (!Array.isArray(value)) return {
+				done: false,
+				value
+			};
+		}
+		return {
+			done: true,
+			value: void 0
+		};
+	} });
+};
+const getParentNodes = (ast) => {
+	const parentNodes = /* @__PURE__ */ new WeakMap();
+	const pending = [{
+		parent: void 0,
+		value: ast
+	}];
+	while (pending.length > 0) {
+		const current = pending.pop();
+		if (!current) continue;
+		const { parent, value } = current;
+		if (Array.isArray(value)) {
+			for (const child of value) pending.push({
+				parent,
+				value: child
+			});
+			continue;
+		}
+		if (!isRecord(value)) continue;
+		if (parent) parentNodes.set(value, parent);
+		for (const child of Object.values(value)) pending.push({
+			parent: value,
+			value: child
+		});
+	}
+	return parentNodes;
+};
+const isRecord = (value) => {
+	return typeof value === "object" && value !== null;
+};
+const getBindingContext = (identifier) => {
+	return "ctxt" in identifier && typeof identifier.ctxt === "number" ? identifier.ctxt : void 0;
+};
+const getDeclaratorImport = (node, imports) => {
+	const initializer = node.init;
+	if (initializer?.type !== "Identifier") return;
+	const imported = imports.get(initializer.value);
+	return imported?.bindingContext !== void 0 && imported.bindingContext === getBindingContext(initializer) ? imported : void 0;
+};
+const addImportedBindings = (pattern, imported, imports) => {
+	if (pattern.type === "Identifier") {
+		const { value: alias } = pattern;
+		const bindingContext = getBindingContext(pattern);
+		const existing = imports.get(alias);
+		if (bindingContext === void 0 || existing && existing.bindingContext !== bindingContext) return;
+		imports.set(alias, {
+			...imported,
+			alias,
+			bindingContext
+		});
+		return;
+	}
+	if (pattern.type !== "ObjectPattern") return;
+	for (const property of pattern.properties) {
+		if (property.type === "KeyValuePatternProperty") {
+			if (property.key.type === "Identifier" || property.key.type === "StringLiteral") addImportedBindings(property.value, {
+				...imported,
+				name: property.key.value
+			}, imports);
+			continue;
+		}
+		if (property.type === "AssignmentPatternProperty") addImportedBindings(property.key, {
+			...imported,
+			name: property.key.value
+		}, imports);
+	}
+};
+const getJSXAttributeValue = (node) => {
+	if (!node) return true;
+	if (node.type === "BigIntLiteral" || node.type === "BooleanLiteral" || node.type === "JSXText" || node.type === "NumericLiteral" || node.type === "StringLiteral") return node.value;
+	if (node.type === "JSXExpressionContainer") return getJSXAttributeValue(node.expression);
+	if (node.type === "NullLiteral") return;
+	return createUnknownToken(node.type);
+};
+/**
+* Creates a placeholder for an unsupported source expression.
+*
+* @example
+* 	createUnknownToken("VariableDeclaration");
+*
+* @param syntax - SWC syntax node name.
+* @returns A placeholder identifying the unsupported expression.
+*/
+const createUnknownToken = (syntax) => {
+	return {
+		syntax,
+		type: "unsupported-syntax"
+	};
+};
+
+// src/modules/scanner/scan.ts
+const execFileAsync = promisify(execFile);
+const DEFAULT_EXCLUDED_FOLDERS = [
+	".git",
+	"node_modules",
+	"dist",
+	"out"
+];
+const DEFAULT_INCLUDED_FILES = ["**/!(test|*.test|stories|*.stories).?(m){j,t}s?(x)"];
+/**
+* Finds matching source files in the package tree at `path`.
+*
+* @param path - Root directory to scan.
+* @param signal - Cancels the scan.
+* @param options - File and folder filters.
+* @returns A backpressure-aware stream of matching source files and their package metadata.
+*/
+const scan = (path, signal, options) => {
+	const excludedFolders = new Set(options.excludeFolders ?? DEFAULT_EXCLUDED_FOLDERS);
+	const includedFiles = options.includeFiles ?? DEFAULT_INCLUDED_FILES;
+	const isIncluded = (file, project) => {
+		const relativeFile = relative(project.folder, file).replaceAll(sep, "/");
+		return includedFiles.some((pattern) => {
+			return matchesGlob(relativeFile, pattern);
+		});
+	};
+	const scanDirectory = (folder, parentProject) => {
+		return Readable.from([folder]).flatMap(async () => {
+			const project = await getProject(folder) ?? parentProject;
+			return Readable.from(await opendir(folder)).flatMap((entry) => {
+				const file = join(folder, entry.name);
+				if (entry.isDirectory() && excludedFolders.has(entry.name)) return [];
+				if (entry.isDirectory()) return scanDirectory(file, project);
+				const isSourceFile = entry.isFile() || entry.isSymbolicLink();
+				if (!project || !isSourceFile || !isIncluded(file, project)) return [];
+				return [{
+					...project,
+					file
+				}];
+			}, { signal });
+		});
+	};
+	return scanDirectory(path);
+};
+const getProject = async (folder) => {
+	try {
+		const content = await readFile(join(folder, "package.json"), "utf8");
+		return {
+			metadata: JSON.parse(content),
+			folder,
+			link: await getRepositoryUrl(folder)
+		};
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return;
+		throw error;
+	}
+};
+const getRepositoryUrl = async (folder) => {
+	try {
+		const { stdout } = await execFileAsync("git", [
+			"config",
+			"--get",
+			"remote.origin.url"
+		], { cwd: folder });
+		return stdout.trim();
+	} catch {
+		return "";
+	}
+};
+
+// src/create-instance.ts
+/**
+* Creates an analyzer for the package tree at `path`.
+*
+* @param path - Root directory to scan.
+* @param options - Optional file filters, module filters, and parser plugins.
+* @returns An analyzer that collects matching SDK usages.
+*/
+const createInstance = (path, options) => {
+	const { includeModules = [], plugins = [], resolveInstalledVersions = false } = options;
+	const getFileItems = async ({ metadata, file, link }, signal) => {
+		const code = await readFile(file, {
+			encoding: "utf8",
+			signal
+		});
+		const items = await parse$1(code, {
+			file,
+			plugins
+		});
+		const locate = createLocator({
+			code,
+			file,
+			link,
+			module: metadata.name,
+			path
+		});
+		const dependencies = {
+			...metadata.devDependencies,
+			...metadata.optionalDependencies,
+			...metadata.dependencies
+		};
+		return items.filter(({ module }) => {
+			return includeModules.length === 0 || includeModules.includes(module);
+		}).map((item) => {
+			const version = (resolveInstalledVersions ? getInstalledVersion(item.module, file) : void 0) ?? dependencies[item.module] ?? "";
+			return createItem({
+				...item,
+				location: locate(item.offset),
+				version
+			});
+		});
+	};
+	return { 
+	/**
+	* Collects matching SDK usages from the package tree. Stopping iteration cancels pending
+	* scans; scans already in progress may finish.
+	*
+	* @returns An async iterable of matching SDK usages with their source locations and
+	*   versions.
+	*/
+getItems() {
+		const controller = new AbortController();
+		const { signal } = controller;
+		const iterator = scan(path, signal, options).flatMap(async (file) => {
+			return getFileItems(file, signal);
+		}).iterator();
+		return {
+			next: iterator.next.bind(iterator),
+			async return() {
+				controller.abort();
+				await iterator.return?.();
+				return {
+					done: true,
+					value: void 0
+				};
+			},
+			[Symbol.asyncIterator]() {
+				return this;
+			}
+		};
+	} };
+};
+const getInstalledVersion = (module, file) => {
+	try {
+		const { version } = require(resolvePackageJson(require.resolve(module, { paths: [file] })));
+		return version;
+	} catch {
+		return;
+	}
+};
+
+// src/modules/plugin/create-plugin.ts
+/**
+* Returns a plugin definition unchanged for convenient type inference.
+*
+* @param input - Plugin implementation.
+* @returns The supplied plugin implementation.
+*/
+const createPlugin = (input) => {
+	return input;
+};
+
+export { createInstance, createPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdk-usage/core",
-  "version": "0.2.0-next.1794009490550.b76492b",
+  "version": "0.2.0",
   "description": "Core APIs for scanning package source and collecting SDK usage through syntax plugins.",
   "keywords": [
     "analyze",