@webneat/codewiki 0.0.2 → 0.0.5

package/dist/index.js

@@ -4,12 +4,18 @@ var __export = (target, all3) => {
     __defProp(target, name, { get: all3[name], enumerable: true });
 };
 
+// ../../node_modules/.pnpm/tsup@8.5.0_postcss@8.5.6_tsx@4.20.6_typescript@5.9.3_yaml@2.8.1/node_modules/tsup/assets/esm_shims.js
+import path from "path";
+import { fileURLToPath } from "url";
+var getFilename = () => fileURLToPath(import.meta.url);
+var getDirname = () => path.dirname(getFilename());
+var __dirname = /* @__PURE__ */ getDirname();
+
 // src/internals/context.ts
 import ts from "typescript";
-import { fileURLToPath } from "url";
 import Database from "better-sqlite3";
 import { readFile as readFile2 } from "fs/promises";
-import path, { dirname, join as join2 } from "path";
+import path2, { join as join2 } from "path";
 import { drizzle } from "drizzle-orm/better-sqlite3";
 
 // ../errors/dist/index.js
@@ -73,6 +79,7 @@ var index_default = errors;
 var err = index_default({
   file_outside_project_path: (data) => `File "${data.file_path}" is outside project path "${data.project_path}"`,
   file_not_found: (data) => `File not found: ${data.path}`,
+  file_stat_error: (data) => `Could not get file stats for ${data.path}: ${data.reason}`,
   db_error: (data) => `Database error in ${data.operation}: ${data.reason}`,
   symbol_meta_parse_error: (data) => `Failed to parse symbol metadata for symbol ${data.symbol_id}: ${data.reason}`,
   exported_symbol_not_found: (data) => `Exported symbol "${data.name}" not found in file with id ${data.file_id}`,
@@ -85,6 +92,8 @@ var err = index_default({
   symbol_node_not_found: (data) => `Symbol node not found for ${data.name} in ${data.file_path}`,
   symbol_not_found: (data) => `Symbol "${data.name}" not found in file "${data.path}"`,
   describe_dependency_failed: (data) => `Failed to describe ${data.package}#${data.name}: ${data.reason}`,
+  could_not_describe_files_due_to_pending_symbols: (data) => `Cannot start describing files before describing all symbols; ${data.count} symbols are still pending`,
+  could_not_describe_directories_due_to_pending_files: (data) => `Cannot start describing directories before describing all files; ${data.count} files are still pending`,
   // CLI errors
   could_not_read_file: (data) => `Could not read file ${data.path}: ${data.reason}`,
   invalid_json: (data) => `Invalid JSON: ${data.reason}`,
@@ -437,7 +446,7 @@ __export(configs_exports, {
 import { eq as eq2, sql as sql3 } from "drizzle-orm";
 
 // src/db/common.ts
-import { eq, like, or, and, asc, desc } from "drizzle-orm";
+import { eq, like, or, and, asc, desc, count } from "drizzle-orm";
 function safe_query(operation, fn) {
   return err.safe(fn, (reason, ...args) => err.new("db_error", { operation, args: args.slice(1), reason }));
 }
@@ -445,6 +454,9 @@ function do_search(db6, table, options) {
   if (!options.select.includes("id")) options.select.push("id");
   return db6.select(fields(table, options.select)).from(table).where(conditions(table, options.where)).orderBy(order(table, options.order_by)).offset(options.offset).limit(options.limit).all();
 }
+function do_count(db6, table, options) {
+  return db6.select({ count: count() }).from(table).where(conditions(table, options)).get()?.count ?? 0;
+}
 function fields(table, fields2) {
   const res = {};
   for (const field of fields2) res[field] = table[field];
@@ -496,8 +508,10 @@ __export(files_exports, {
   by_directory_path: () => by_directory_path,
   by_id: () => by_id,
   by_id_and_state: () => by_id_and_state,
+  by_ids: () => by_ids,
   by_path: () => by_path,
   by_state: () => by_state,
+  count: () => count2,
   del: () => del,
   del_by_dir: () => del_by_dir,
   get_directory_ids: () => get_directory_ids,
@@ -512,11 +526,15 @@ __export(files_exports, {
 import { eq as eq3, and as and2, inArray, or as or2, like as like2 } from "drizzle-orm";
 
 // src/internals/utils.ts
-import { readFileSync } from "fs";
+import { readFileSync, statSync } from "fs";
 var parse_json = err.safe(JSON.parse, (reason, text2) => err.new("invalid_json", { reason, text: text2 }));
 var read_file = err.safe(
-  (path6) => readFileSync(path6, "utf-8"),
-  (reason, path6) => err.new("could_not_read_file", { path: path6, reason })
+  (path7) => readFileSync(path7, "utf-8"),
+  (reason, path7) => err.new("could_not_read_file", { path: path7, reason })
+);
+var file_stat = err.safe(
+  (path7) => statSync(path7),
+  (reason, path7) => err.new("file_stat_error", { path: path7, reason })
 );
 function group_by_unique(items, key) {
   const groups = {};
@@ -582,6 +600,34 @@ var external_dependencies2 = {
   offset: 0,
   where: {}
 };
+var imports2 = {
+  select: ["id", "exporter_file_id", "importer_file_id", "symbol_id", "name", "alias", "is_dynamic", "state", "error"],
+  order_by: ["id", "asc"],
+  limit: 20,
+  offset: 0,
+  where: {}
+};
+var external_imports2 = {
+  select: ["id", "file_id", "external_dependency_id", "alias", "is_dynamic"],
+  order_by: ["id", "asc"],
+  limit: 20,
+  offset: 0,
+  where: {}
+};
+var symbol_internal_links2 = {
+  select: ["id", "from_file_id", "to_file_id", "from_symbol_id", "to_symbol_id", "state", "error"],
+  order_by: ["id", "asc"],
+  limit: 20,
+  offset: 0,
+  where: {}
+};
+var symbol_external_links2 = {
+  select: ["id", "symbol_id", "external_import_id"],
+  order_by: ["id", "asc"],
+  limit: 20,
+  offset: 0,
+  where: {}
+};
 
 // src/db/files.ts
 var default_select_fields = ["id", "directory_id", "path", "state", "error"];
@@ -589,15 +635,23 @@ var all = safe_query("files.all", (ctx) => ctx.db.select().from(files).all());
 var search = safe_query("files.search", (ctx, options = {}) => {
   return do_search(ctx.db, files, merge(files2, options));
 });
+var count2 = safe_query("files.count", (ctx, where = {}) => {
+  return do_count(ctx.db, files, where);
+});
 var by_id = safe_query("files.by_id", (ctx, id) => ctx.db.select().from(files).where(eq3(files.id, id)).get());
+var by_ids = safe_query(
+  "files.by_ids",
+  (ctx, ids) => ctx.db.select().from(files).where(inArray(files.id, ids)).all()
+);
 var by_path = safe_query(
   "files.by_path",
-  (ctx, path6) => ctx.db.select().from(files).where(eq3(files.path, path6)).get()
-);
-var by_state = safe_query(
-  "files.by_state",
-  (ctx, state) => ctx.db.select().from(files).where(eq3(files.state, state)).all()
+  (ctx, path7) => ctx.db.select().from(files).where(eq3(files.path, path7)).get()
 );
+var by_state = safe_query("files.by_state", (ctx, state, limit) => {
+  let query = ctx.db.select().from(files).where(eq3(files.state, state));
+  if (limit) query = query.limit(limit);
+  return query.all();
+});
 var insert = safe_query("files.insert", (ctx, values) => ctx.db.insert(files).values(values).run());
 var update = safe_query(
   "files.update",
@@ -639,8 +693,8 @@ var using_dependency = safe_query(
   "files.using_dependency",
   (ctx, external_dependency_id, fields_to_select = default_select_fields) => {
     if (!fields_to_select.includes("id")) fields_to_select.push("id");
-    const imports2 = ctx.db.select({ file_id: external_imports.file_id }).from(external_imports).where(eq3(external_imports.external_dependency_id, external_dependency_id)).all();
-    const file_ids = uniq(imports2.map((i) => i.file_id));
+    const imports4 = ctx.db.select({ file_id: external_imports.file_id }).from(external_imports).where(eq3(external_imports.external_dependency_id, external_dependency_id)).all();
+    const file_ids = uniq(imports4.map((i) => i.file_id));
     if (file_ids.length === 0) return [];
     return ctx.db.select(fields(files, fields_to_select)).from(files).where(inArray(files.id, file_ids)).all();
   }
@@ -671,8 +725,10 @@ var directories_exports = {};
 __export(directories_exports, {
   by_id: () => by_id2,
   by_id_and_state: () => by_id_and_state2,
+  by_ids: () => by_ids2,
   by_path: () => by_path2,
   by_state: () => by_state2,
+  count: () => count3,
   insert: () => insert2,
   search: () => search2,
   update: () => update2,
@@ -683,9 +739,13 @@ var by_id2 = safe_query(
   "directories.by_id",
   (ctx, id) => ctx.db.select().from(directories).where(eq4(directories.id, id)).get()
 );
+var by_ids2 = safe_query(
+  "directories.by_ids",
+  (ctx, ids) => ctx.db.select().from(directories).where(inArray2(directories.id, ids)).all()
+);
 var by_path2 = safe_query(
   "directories.by_path",
-  (ctx, path6) => ctx.db.select().from(directories).where(eq4(directories.path, path6)).get()
+  (ctx, path7) => ctx.db.select().from(directories).where(eq4(directories.path, path7)).get()
 );
 var by_state2 = safe_query(
   "directories.by_state",
@@ -710,6 +770,9 @@ var by_id_and_state2 = safe_query(
 var search2 = safe_query("directories.search", (ctx, options = {}) => {
   return do_search(ctx.db, directories, merge(directories2, options));
 });
+var count3 = safe_query("directories.count", (ctx, where = {}) => {
+  return do_count(ctx.db, directories, where);
+});
 
 // src/db/imports.ts
 var imports_exports = {};
@@ -717,11 +780,23 @@ __export(imports_exports, {
   by_exporter_file: () => by_exporter_file,
   by_importer_file: () => by_importer_file,
   by_state: () => by_state3,
+  count: () => count4,
+  count_pending_symbols: () => count_pending_symbols,
   del_by_importer_file: () => del_by_importer_file,
   insert_many: () => insert_many,
+  search: () => search3,
   update: () => update3
 });
-import { eq as eq5 } from "drizzle-orm";
+import { eq as eq5, ne, and as and4, count as countFn } from "drizzle-orm";
+var search3 = safe_query("imports.search", (ctx, options = {}) => {
+  return do_search(ctx.db, imports, merge(imports2, options));
+});
+var count4 = safe_query("imports.count", (ctx, where = {}) => {
+  return do_count(ctx.db, imports, where);
+});
+var count_pending_symbols = safe_query("imports.count_pending_symbols", (ctx, file_id) => {
+  return ctx.db.select({ count: countFn() }).from(imports).innerJoin(symbols, eq5(imports.symbol_id, symbols.id)).where(and4(eq5(imports.importer_file_id, file_id), ne(symbols.state, "ready"))).get()?.count ?? 0;
+});
 var by_exporter_file = safe_query(
   "imports.by_exporter_file",
   (ctx, exporter_file_id) => ctx.db.select().from(imports).where(eq5(imports.exporter_file_id, exporter_file_id)).all()
@@ -751,17 +826,19 @@ __export(symbols_exports, {
   by_file_and_name: () => by_file_and_name,
   by_id: () => by_id3,
   by_id_and_state: () => by_id_and_state3,
+  by_ids: () => by_ids3,
   by_state: () => by_state4,
+  count: () => count5,
   del_by_file: () => del_by_file,
   insert_many: () => insert_many2,
   meta: () => meta,
   referenced_by: () => referenced_by,
   referencing: () => referencing,
-  search: () => search3,
+  search: () => search4,
   update: () => update4,
   using_dependency: () => using_dependency2
 });
-import { eq as eq6, and as and4, inArray as inArray3 } from "drizzle-orm";
+import { eq as eq6, and as and5, inArray as inArray3 } from "drizzle-orm";
 var insert_many2 = safe_query("symbols.insert_many", (ctx, values) => ctx.db.insert(symbols).values(values).run());
 var del_by_file = safe_query(
   "symbols.delete_by_file",
@@ -769,7 +846,7 @@ var del_by_file = safe_query(
 );
 var by_file_and_name = safe_query(
   "symbols.by_file_and_name",
-  (ctx, params) => ctx.db.select().from(symbols).where(and4(eq6(symbols.file_id, params.file_id), eq6(symbols.name, params.name), eq6(symbols.is_exported, params.is_exported))).get()
+  (ctx, params) => ctx.db.select().from(symbols).where(and5(eq6(symbols.file_id, params.file_id), eq6(symbols.name, params.name), eq6(symbols.is_exported, params.is_exported))).get()
 );
 var by_state4 = safe_query(
   "symbols.by_state",
@@ -784,9 +861,13 @@ var update4 = safe_query(
   (ctx, id, data) => ctx.db.update(symbols).set(data).where(eq6(symbols.id, id)).run()
 );
 var by_id3 = safe_query("symbols.by_id", (ctx, id) => ctx.db.select().from(symbols).where(eq6(symbols.id, id)).get());
+var by_ids3 = safe_query(
+  "symbols.by_ids",
+  (ctx, ids) => ctx.db.select().from(symbols).where(inArray3(symbols.id, ids)).all()
+);
 var by_id_and_state3 = safe_query(
   "symbols.by_id_and_state",
-  (ctx, params) => ctx.db.select().from(symbols).where(and4(eq6(symbols.id, params.id), eq6(symbols.state, params.state))).get()
+  (ctx, params) => ctx.db.select().from(symbols).where(and5(eq6(symbols.id, params.id), eq6(symbols.state, params.state))).get()
 );
 function meta(symbol) {
   return err.catch(
@@ -794,8 +875,12 @@ function meta(symbol) {
     (reason) => err.new("symbol_meta_parse_error", { reason, symbol_id: symbol.id, meta: symbol.meta })
   );
 }
-var search3 = safe_query("symbols.search", (ctx, options = {}) => {
-  return do_search(ctx.db, symbols, merge(symbols2, options));
+var search4 = safe_query(
+  "symbols.search",
+  (ctx, options = {}) => do_search(ctx.db, symbols, merge(symbols2, options))
+);
+var count5 = safe_query("symbols.count", (ctx, where = {}) => {
+  return do_count(ctx.db, symbols, where);
 });
 var referenced_by = safe_query(
   "symbols.referenced_by",
@@ -833,20 +918,26 @@ var external_dependencies_exports = {};
 __export(external_dependencies_exports, {
   all: () => all2,
   by_id: () => by_id4,
+  by_ids: () => by_ids4,
   by_package_subpath_and_name: () => by_package_subpath_and_name,
   by_state: () => by_state5,
+  count: () => count6,
   get_or_create: () => get_or_create,
   insert: () => insert3,
-  search: () => search4,
+  search: () => search5,
   update: () => update5,
   used_by_file: () => used_by_file,
   used_by_symbol: () => used_by_symbol
 });
-import { eq as eq7, and as and5, sql as sql4, inArray as inArray4 } from "drizzle-orm";
+import { eq as eq7, and as and6, sql as sql4, inArray as inArray4 } from "drizzle-orm";
 var by_id4 = safe_query(
   "external_dependencies.by_id",
   (ctx, id) => ctx.db.select().from(external_dependencies).where(eq7(external_dependencies.id, id)).get()
 );
+var by_ids4 = safe_query(
+  "external_dependencies.by_ids",
+  (ctx, ids) => ctx.db.select().from(external_dependencies).where(inArray4(external_dependencies.id, ids)).all()
+);
 var by_state5 = safe_query(
   "external_dependencies.by_state",
   (ctx, state) => ctx.db.select().from(external_dependencies).where(eq7(external_dependencies.state, state)).all()
@@ -854,7 +945,7 @@ var by_state5 = safe_query(
 var by_package_subpath_and_name = safe_query(
   "external_dependencies.by_package_subpath_and_name",
   (ctx, params) => ctx.db.select().from(external_dependencies).where(
-    and5(
+    and6(
       eq7(external_dependencies.package, params.package),
       params.subpath === null ? sql4`${external_dependencies.subpath} IS NULL` : eq7(external_dependencies.subpath, params.subpath),
       params.name === null ? sql4`${external_dependencies.name} IS NULL` : eq7(external_dependencies.name, params.name)
@@ -876,11 +967,13 @@ function get_or_create(ctx, value) {
     (existing) => existing || insert3(ctx, value)
   );
 }
-var search4 = safe_query(
+var search5 = safe_query(
   "external_dependencies.search",
-  (ctx, options = {}) => {
-    return do_search(ctx.db, external_dependencies, merge(external_dependencies2, options));
-  }
+  (ctx, options = {}) => do_search(ctx.db, external_dependencies, merge(external_dependencies2, options))
+);
+var count6 = safe_query(
+  "external_dependencies.count",
+  (ctx, where = {}) => do_count(ctx.db, external_dependencies, where)
 );
 var used_by_file = safe_query(
   "external_dependencies.used_by_file",
@@ -912,10 +1005,22 @@ __export(external_imports_exports, {
   by_external_dependency: () => by_external_dependency,
   by_file: () => by_file2,
   by_symbol: () => by_symbol,
+  count: () => count7,
+  count_pending_dependencies: () => count_pending_dependencies,
   del_by_file: () => del_by_file2,
-  insert_many: () => insert_many3
+  insert_many: () => insert_many3,
+  search: () => search6
+});
+import { eq as eq8, ne as ne2, and as and7, count as countFn2 } from "drizzle-orm";
+var search6 = safe_query("external_imports.search", (ctx, options = {}) => {
+  return do_search(ctx.db, external_imports, merge(external_imports2, options));
+});
+var count7 = safe_query("external_imports.count", (ctx, where = {}) => {
+  return do_count(ctx.db, external_imports, where);
+});
+var count_pending_dependencies = safe_query("external_imports.count_pending_dependencies", (ctx, file_id) => {
+  return ctx.db.select({ count: countFn2() }).from(external_imports).innerJoin(external_dependencies, eq8(external_imports.external_dependency_id, external_dependencies.id)).where(and7(eq8(external_imports.file_id, file_id), ne2(external_dependencies.state, "ready"))).get()?.count ?? 0;
 });
-import { eq as eq8 } from "drizzle-orm";
 var insert_many3 = safe_query(
   "external_imports.insert_many",
   (ctx, values) => ctx.db.insert(external_imports).values(values).run()
@@ -950,11 +1055,20 @@ var by_symbol = safe_query(
 var symbol_internal_links_exports = {};
 __export(symbol_internal_links_exports, {
   by_from_symbol: () => by_from_symbol,
+  count: () => count8,
   del_by_from_symbol: () => del_by_from_symbol,
   exists: () => exists,
-  insert: () => insert4
+  insert: () => insert4,
+  search: () => search7,
+  update_state_by_to_symbol: () => update_state_by_to_symbol
+});
+import { and as and8, eq as eq9 } from "drizzle-orm";
+var search7 = safe_query("symbol_internal_links.search", (ctx, options = {}) => {
+  return do_search(ctx.db, symbol_internal_links, merge(symbol_internal_links2, options));
+});
+var count8 = safe_query("symbol_internal_links.count", (ctx, where = {}) => {
+  return do_count(ctx.db, symbol_internal_links, where);
 });
-import { and as and6, eq as eq9 } from "drizzle-orm";
 var by_from_symbol = safe_query(
   "symbol_internal_links.by_from_symbol",
   (ctx, from_symbol_id) => ctx.db.query.symbol_internal_links.findMany({
@@ -974,23 +1088,43 @@ var insert4 = safe_query(
 );
 var exists = safe_query(
   "symbol_internal_links.exists",
-  (ctx, params) => ctx.db.select({ id: symbol_internal_links.id }).from(symbol_internal_links).where(and6(eq9(symbol_internal_links.from_symbol_id, params.from_symbol_id), eq9(symbol_internal_links.to_symbol_id, params.to_symbol_id))).get()
+  (ctx, params) => ctx.db.select({ id: symbol_internal_links.id }).from(symbol_internal_links).where(and8(eq9(symbol_internal_links.from_symbol_id, params.from_symbol_id), eq9(symbol_internal_links.to_symbol_id, params.to_symbol_id))).get()
 );
 var del_by_from_symbol = safe_query(
   "symbol_internal_links.del_by_from_symbol",
   (ctx, from_symbol_id) => ctx.db.delete(symbol_internal_links).where(eq9(symbol_internal_links.from_symbol_id, from_symbol_id)).run()
 );
+var update_state_by_to_symbol = safe_query(
+  "symbol_internal_links.update_state_by_to_symbol",
+  (ctx, to_symbol_id, state) => ctx.db.update(symbol_internal_links).set({ state }).where(eq9(symbol_internal_links.to_symbol_id, to_symbol_id)).run()
+);
 
 // src/db/symbol_external_links.ts
 var symbol_external_links_exports = {};
 __export(symbol_external_links_exports, {
   by_external_import: () => by_external_import,
   by_symbol: () => by_symbol2,
+  count: () => count9,
+  count_by_dependency: () => count_by_dependency,
+  count_pending_deps: () => count_pending_deps,
   del_by_symbol: () => del_by_symbol,
   exists: () => exists2,
-  insert: () => insert5
+  insert: () => insert5,
+  search: () => search8
+});
+import { and as and9, eq as eq10, ne as ne3, count as countFn3 } from "drizzle-orm";
+var search8 = safe_query("symbol_external_links.search", (ctx, options = {}) => {
+  return do_search(ctx.db, symbol_external_links, merge(symbol_external_links2, options));
+});
+var count9 = safe_query("symbol_external_links.count", (ctx, where = {}) => {
+  return do_count(ctx.db, symbol_external_links, where);
+});
+var count_by_dependency = safe_query("symbol_external_links.count_by_dependency", (ctx, dependency_id) => {
+  return ctx.db.select({ count: countFn3() }).from(symbol_external_links).innerJoin(external_imports, eq10(symbol_external_links.external_import_id, external_imports.id)).where(eq10(external_imports.external_dependency_id, dependency_id)).get()?.count ?? 0;
+});
+var count_pending_deps = safe_query("symbol_external_links.count_pending_deps", (ctx, symbol_id) => {
+  return ctx.db.select({ count: countFn3() }).from(symbol_external_links).innerJoin(external_imports, eq10(symbol_external_links.external_import_id, external_imports.id)).innerJoin(external_dependencies, eq10(external_imports.external_dependency_id, external_dependencies.id)).where(and9(eq10(symbol_external_links.symbol_id, symbol_id), ne3(external_dependencies.state, "ready"))).get()?.count ?? 0;
 });
-import { and as and7, eq as eq10 } from "drizzle-orm";
 var by_symbol2 = safe_query(
   "symbol_external_links.by_symbol",
   (ctx, symbol_id) => ctx.db.select().from(symbol_external_links).where(eq10(symbol_external_links.symbol_id, symbol_id)).all()
@@ -1005,7 +1139,7 @@ var by_external_import = safe_query(
 );
 var exists2 = safe_query(
   "symbol_external_links.exists",
-  (ctx, params) => ctx.db.select({ id: symbol_external_links.id }).from(symbol_external_links).where(and7(eq10(symbol_external_links.symbol_id, params.symbol_id), eq10(symbol_external_links.external_import_id, params.external_import_id))).get()
+  (ctx, params) => ctx.db.select({ id: symbol_external_links.id }).from(symbol_external_links).where(and9(eq10(symbol_external_links.symbol_id, params.symbol_id), eq10(symbol_external_links.external_import_id, params.external_import_id))).get()
 );
 var del_by_symbol = safe_query(
   "symbol_external_links.del_by_symbol",
@@ -1014,8 +1148,8 @@ var del_by_symbol = safe_query(
 
 // src/internals/context.ts
 async function create_context(sqlite, db6, config) {
-  const project_path = path.resolve(config.project_path);
-  const currentDir = dirname(fileURLToPath(import.meta.url));
+  const project_path = path2.resolve(config.project_path);
+  const currentDir = __dirname;
   const migrations_path = currentDir.includes("/dist") ? join2(currentDir, "../migrations") : join2(currentDir, "../../migrations");
   const tsconfig_path = join2(project_path, "tsconfig.json");
   if (!ts.sys.fileExists(tsconfig_path)) {
@@ -1023,8 +1157,8 @@ async function create_context(sqlite, db6, config) {
   }
   const tsconfig = ts.parseJsonConfigFileContent(ts.readConfigFile(tsconfig_path, ts.sys.readFile).config, ts.sys, project_path);
   const program = ts.createProgram({ rootNames: tsconfig.fileNames, options: tsconfig.options });
-  const package_json_path = config.package_json_path ?? path.join(project_path, "package.json");
-  const node_modules_paths = config.node_modules_paths ?? [path.join(project_path, "node_modules")];
+  const package_json_path = config.package_json_path ?? path2.join(project_path, "package.json");
+  const node_modules_paths = config.node_modules_paths ?? [path2.join(project_path, "node_modules")];
   const dependencies = await get_dependencies(package_json_path, node_modules_paths);
   const ctx = { db: db6, sqlite, migrations_path, project_path, program, dependencies };
   await migrate(ctx);
@@ -1083,7 +1217,7 @@ async function get_dependencies(package_json_path, node_modules_paths) {
 async function get_github_repo(node_modules_paths, package_name) {
   for (const node_modules_path of node_modules_paths) {
     try {
-      const package_json_path = path.join(node_modules_path, package_name, "package.json");
+      const package_json_path = path2.join(node_modules_path, package_name, "package.json");
       const package_json = JSON.parse(await readFile2(package_json_path, "utf-8"));
       const url = package_json.repository?.url || package_json.repository;
       if (typeof url === "string") {
@@ -1098,7 +1232,7 @@ async function get_github_repo(node_modules_paths, package_name) {
 }
 
 // src/update/track_changes.ts
-import path2 from "path";
+import path3 from "path";
 import "typescript";
 import { stat } from "fs/promises";
 
@@ -1109,9 +1243,9 @@ function file_updated(ctx, file_id) {
       items: [file_id],
       get_key: (id) => id,
       get_children: (id) => {
-        const imports2 = imports_exports.by_exporter_file(ctx, id);
-        if (err.any(imports2)) return imports2;
-        return imports2.map((x) => x.importer_file_id);
+        const imports4 = imports_exports.by_exporter_file(ctx, id);
+        if (err.any(imports4)) return imports4;
+        return imports4.map((x) => x.importer_file_id);
       }
     })
   );
@@ -1144,7 +1278,7 @@ function get_source_files(ctx) {
   for (const file of ctx.program.getSourceFiles()) {
     if (ctx.program.isSourceFileDefaultLibrary(file)) continue;
     if (ctx.program.isSourceFileFromExternalLibrary(file)) continue;
-    if (!path2.resolve(file.fileName).startsWith(ctx.project_path)) continue;
+    if (!path3.resolve(file.fileName).startsWith(ctx.project_path)) continue;
     src_files.push(file);
   }
   return src_files;
@@ -1192,7 +1326,7 @@ async function changes(ctx, source_files, db_files) {
   return { created, updated, deleted };
 }
 function get_file_path(ctx, file) {
-  const absolute_path = path2.resolve(file.fileName);
+  const absolute_path = path3.resolve(file.fileName);
   if (absolute_path.startsWith(ctx.project_path)) return absolute_path.slice(ctx.project_path.length);
   return err.new("file_outside_project_path", { file_path: absolute_path, project_path: ctx.project_path });
 }
@@ -1200,10 +1334,10 @@ function get_parents_paths(ctx, file) {
   const file_path = get_file_path(ctx, file);
   if (err.any(file_path)) return file_path;
   const dirs = [];
-  let current = path2.dirname(file_path);
-  while (current !== path2.sep) {
+  let current = path3.dirname(file_path);
+  while (current !== path3.sep) {
     dirs.push(current);
-    current = path2.dirname(current);
+    current = path3.dirname(current);
   }
   dirs.push(current);
   return dirs.reverse();
@@ -1237,19 +1371,19 @@ async function sync_external_dependencies(ctx) {
 }
 
 // src/update/scan_files/scan_files.ts
-import path4 from "path";
+import path5 from "path";
 import ts10 from "typescript";
 
 // src/update/scan_files/imports.ts
 import ts4 from "typescript";
 
 // src/update/scan_files/common.ts
-import path3 from "path";
+import path4 from "path";
 import ts3 from "typescript";
 function is_external_module(ctx, source_file, module_path) {
   const resolved = ts3.resolveModuleName(module_path, source_file.fileName, ctx.program.getCompilerOptions(), ts3.sys);
   if (!resolved.resolvedModule) return true;
-  const resolved_path = path3.resolve(resolved.resolvedModule.resolvedFileName);
+  const resolved_path = path4.resolve(resolved.resolvedModule.resolvedFileName);
   return !resolved_path.startsWith(ctx.project_path);
 }
 function has_export_modifier(node) {
@@ -1358,13 +1492,13 @@ function is_import(ctx, source_file, node) {
   return !is_external_module(ctx, source_file, node.moduleSpecifier.text);
 }
 function extract_import(ctx, source_file, node, file_id) {
-  const imports2 = [];
+  const imports4 = [];
   const clause = node.importClause;
-  if (!clause || !node.moduleSpecifier || !ts4.isStringLiteral(node.moduleSpecifier)) return imports2;
+  if (!clause || !node.moduleSpecifier || !ts4.isStringLiteral(node.moduleSpecifier)) return imports4;
   const exporter_file_id = resolve_exporter_file(ctx, source_file, node.moduleSpecifier.text);
-  if (err.any(exporter_file_id)) return imports2;
+  if (err.any(exporter_file_id)) return imports4;
   if (clause.name) {
-    imports2.push({
+    imports4.push({
       importer_file_id: file_id,
       exporter_file_id,
       name: "default",
@@ -1374,7 +1508,7 @@ function extract_import(ctx, source_file, node, file_id) {
   }
   if (clause.namedBindings && ts4.isNamedImports(clause.namedBindings)) {
     for (const element of clause.namedBindings.elements) {
-      imports2.push({
+      imports4.push({
         importer_file_id: file_id,
         exporter_file_id,
         name: (element.propertyName || element.name).text,
@@ -1384,7 +1518,7 @@ function extract_import(ctx, source_file, node, file_id) {
     }
   }
   if (clause.namedBindings && ts4.isNamespaceImport(clause.namedBindings)) {
-    imports2.push({
+    imports4.push({
       importer_file_id: file_id,
       exporter_file_id,
       name: "*",
@@ -1392,7 +1526,7 @@ function extract_import(ctx, source_file, node, file_id) {
       state: "to_link"
     });
   }
-  return imports2;
+  return imports4;
 }
 function extract_dynamic_import(ctx, source_file, node, file_id) {
   const arg = node.arguments[0];
@@ -1504,7 +1638,7 @@ function extract_external_import_info(node) {
 }
 function extract_external_import(ctx, node, file_id) {
   const infos = extract_external_import_info(node);
-  const external_imports2 = [];
+  const external_imports3 = [];
   for (const info of infos) {
     const dep_meta = Object.values(ctx.dependencies).find((dep) => info.package.startsWith(dep.name));
     const dependency = external_dependencies_exports.get_or_create(ctx, {
@@ -1517,9 +1651,9 @@ function extract_external_import(ctx, node, file_id) {
       state: "to_describe"
     });
     if (err.any(dependency)) return dependency;
-    external_imports2.push({ file_id, external_dependency_id: dependency.id, alias: info.alias, is_dynamic: false });
+    external_imports3.push({ file_id, external_dependency_id: dependency.id, alias: info.alias, is_dynamic: false });
   }
-  return external_imports2;
+  return external_imports3;
 }
 function extract_external_dynamic_import(ctx, node, file_id) {
   const arg = node.arguments[0];
@@ -1824,32 +1958,32 @@ function scan_file(ctx, file) {
     () => external_imports_exports.del_by_file(ctx, file.id),
     () => get_source_file(ctx, file.path),
     (source_file) => parse_file(ctx, source_file, file.id),
-    ({ imports: imports2, symbols: symbols3, external_imports: external_imports2 }) => err.pipe(
-      () => external_imports2.length && external_imports_exports.insert_many(ctx, external_imports2),
-      () => imports2.length && imports_exports.insert_many(ctx, imports2),
+    ({ imports: imports4, symbols: symbols3, external_imports: external_imports3 }) => err.pipe(
+      () => external_imports3.length && external_imports_exports.insert_many(ctx, external_imports3),
+      () => imports4.length && imports_exports.insert_many(ctx, imports4),
       () => symbols3.length && symbols_exports.insert_many(ctx, symbols3)
     )
   );
 }
 function get_source_file(ctx, file_path) {
-  const source_file = ctx.program.getSourceFile(path4.join(ctx.project_path, file_path));
+  const source_file = ctx.program.getSourceFile(path5.join(ctx.project_path, file_path));
   if (!source_file) return err.new("file_not_found", { path: file_path });
   return source_file;
 }
 function parse_file(ctx, source_file, file_id) {
-  const imports2 = [];
+  const imports4 = [];
   const symbols3 = [];
-  const external_imports2 = [];
+  const external_imports3 = [];
   function find_dynamic_imports(node) {
     if (is_dynamic_import(node)) {
       const arg = node.arguments[0];
       if (is_external_module(ctx, source_file, arg.text)) {
         const result = extract_external_dynamic_import(ctx, node, file_id);
         if (err.any(result)) return result;
-        external_imports2.push(result);
+        external_imports3.push(result);
       } else {
         const result = extract_dynamic_import(ctx, source_file, node, file_id);
-        if (result) imports2.push(result);
+        if (result) imports4.push(result);
       }
     }
     ts10.forEachChild(node, find_dynamic_imports);
@@ -1862,24 +1996,24 @@ function parse_file(ctx, source_file, file_id) {
       error = res;
       return;
     }
-    imports2.push(...res.imports);
+    imports4.push(...res.imports);
     symbols3.push(...res.symbols);
-    external_imports2.push(...res.external_imports);
+    external_imports3.push(...res.external_imports);
     error = find_dynamic_imports(statement);
   });
   if (error) return error;
-  return { imports: imports2, symbols: symbols3, external_imports: external_imports2 };
+  return { imports: imports4, symbols: symbols3, external_imports: external_imports3 };
 }
 function parse_node(ctx, source_file, node, file_id) {
-  const imports2 = [];
+  const imports4 = [];
   const symbols3 = [];
-  const external_imports2 = [];
+  const external_imports3 = [];
   if (is_external_import(ctx, source_file, node)) {
     const result = extract_external_import(ctx, node, file_id);
     if (err.any(result)) return result;
-    external_imports2.push(...result);
+    external_imports3.push(...result);
   } else if (is_import(ctx, source_file, node)) {
-    imports2.push(...extract_import(ctx, source_file, node, file_id));
+    imports4.push(...extract_import(ctx, source_file, node, file_id));
   } else if (ts10.isExportAssignment(node) && !node.isExportEquals) {
     symbols3.push({
       file_id,
@@ -1921,14 +2055,14 @@ function parse_node(ctx, source_file, node, file_id) {
     symbols3.push(extract_class_symbol(node, file_id, source_file));
     symbols3.push(...extract_class_fields(node, file_id, source_file));
   }
-  return { imports: imports2, symbols: symbols3, external_imports: external_imports2 };
+  return { imports: imports4, symbols: symbols3, external_imports: external_imports3 };
 }
 
 // src/update/link_imports.ts
 async function link_imports(ctx) {
-  const imports2 = err.or_throw(imports_exports.by_state(ctx, "to_link"));
+  const imports4 = err.or_throw(imports_exports.by_state(ctx, "to_link"));
   let i = 0;
-  for (const import_ of imports2) {
+  for (const import_ of imports4) {
     const res = link_import(ctx, import_);
     if (err.any(res)) err.or_throw(imports_exports.update(ctx, import_.id, { error: String(res) }));
   }
@@ -1944,7 +2078,7 @@ function link_import(ctx, import_) {
 }
 
 // src/update/link_symbols.ts
-import path5 from "path";
+import path6 from "path";
 import ts11 from "typescript";
 async function link_symbols(ctx) {
   const symbols3 = err.or_throw(symbols_exports.by_state(ctx, "to_link"));
@@ -1970,7 +2104,7 @@ function find_symbol_references(ctx, symbol) {
   const file = files_exports.by_id(ctx, symbol.file_id);
   if (err.any(file)) return file;
   if (!file) return err.new("file_not_found", { path: `file_id=${symbol.file_id}` });
-  const file_path = path5.join(ctx.project_path, file.path);
+  const file_path = path6.join(ctx.project_path, file.path);
   const source_file = ctx.program.getSourceFile(file_path);
   if (!source_file) return err.new("file_not_found", { path: file_path });
   const symbol_node = find_symbol_node(source_file, symbol);
@@ -2194,19 +2328,19 @@ async function update6(ctx) {
 }
 
 // src/counts.ts
-import { count } from "drizzle-orm";
-var counts = safe_query("counts", (ctx) => {
-  const symbol_counts = ctx.db.select({ state: symbols.state, count: count() }).from(symbols).groupBy(symbols.state).all();
-  const file_counts = ctx.db.select({ state: files.state, count: count() }).from(files).groupBy(files.state).all();
-  const dir_counts = ctx.db.select({ state: directories.state, count: count() }).from(directories).groupBy(directories.state).all();
-  const dep_counts = ctx.db.select({ state: external_dependencies.state, count: count() }).from(external_dependencies).groupBy(external_dependencies.state).all();
+import { count as count10 } from "drizzle-orm";
+function counts(ctx) {
+  const symbol_counts = ctx.db.select({ state: symbols.state, count: count10() }).from(symbols).groupBy(symbols.state).all();
+  const file_counts = ctx.db.select({ state: files.state, count: count10() }).from(files).groupBy(files.state).all();
+  const dir_counts = ctx.db.select({ state: directories.state, count: count10() }).from(directories).groupBy(directories.state).all();
+  const dep_counts = ctx.db.select({ state: external_dependencies.state, count: count10() }).from(external_dependencies).groupBy(external_dependencies.state).all();
   return {
     symbols: get_groups(symbol_counts, ["to_link", "to_describe", "ready"]),
     files: get_groups(file_counts, ["to_scan", "to_describe", "ready"]),
     directories: get_groups(dir_counts, ["to_describe", "ready"]),
     dependencies: get_groups(dep_counts, ["to_describe", "ready"])
   };
-});
+}
 function get_groups(items, states) {
   const groups = { total: 0 };
   for (const state of states) groups[state] = 0;
@@ -2222,7 +2356,7 @@ function get_groups(items, states) {
 function files_wiki(ctx) {
   return {
     get: (id) => get2(ctx, id),
-    search: (options) => search5(ctx, options),
+    search: (options) => search9(ctx, options),
     set_description: (id, description) => set_description(ctx, id, description),
     imported_by_file: (file_id, options) => imported_by_file(ctx, file_id, options),
     importing_file: (file_id, options) => importing_file(ctx, file_id, options),
@@ -2232,11 +2366,11 @@ function files_wiki(ctx) {
 function get2(ctx, id) {
   return err.or_throw(files_exports.by_id(ctx, id)) ?? null;
 }
-function search5(ctx, options) {
+function search9(ctx, options) {
   return err.or_throw(files_exports.search(ctx, options));
 }
 function set_description(ctx, id, description) {
-  err.or_throw(files_exports.update(ctx, id, { description }));
+  err.or_throw(files_exports.update(ctx, id, { description, state: "ready", error: null }));
 }
 function imported_by_file(ctx, file_id, options = {}) {
   let imported_files = err.or_throw(files_exports.imported_by(ctx, file_id, options.select));
@@ -2288,7 +2422,7 @@ function importing_dependency(ctx, dependency_id, options = {}) {
 function symbols_wiki(ctx) {
   return {
     get: (id) => get3(ctx, id),
-    search: (options) => search6(ctx, options),
+    search: (options) => search10(ctx, options),
     set_description: (id, description) => set_description2(ctx, id, description),
     referencing_symbol: (symbol_id, options) => referencing_symbol(ctx, symbol_id, options),
     referenced_by_symbol: (symbol_id, options) => referenced_by_symbol(ctx, symbol_id, options),
@@ -2298,11 +2432,12 @@ function symbols_wiki(ctx) {
 function get3(ctx, id) {
   return err.or_throw(symbols_exports.by_id(ctx, id)) ?? null;
 }
-function search6(ctx, options) {
+function search10(ctx, options) {
   return err.or_throw(symbols_exports.search(ctx, options));
 }
 function set_description2(ctx, id, description) {
-  err.or_throw(symbols_exports.update(ctx, id, { description }));
+  err.or_throw(symbols_exports.update(ctx, id, { description, state: "ready", error: null }));
+  err.or_throw(symbol_internal_links_exports.update_state_by_to_symbol(ctx, id, "ready"));
 }
 function referenced_by_symbol(ctx, symbol_id, options = {}) {
   let referenced_symbols = err.or_throw(symbols_exports.referenced_by(ctx, symbol_id, options.select));
@@ -2354,7 +2489,7 @@ function using_dependency3(ctx, dependency_id, options = {}) {
 function directories_wiki(ctx) {
   return {
     get: (id) => get4(ctx, id),
-    search: (options) => search7(ctx, options),
+    search: (options) => search11(ctx, options),
     set_description: (id, description) => set_description3(ctx, id, description),
     children: (parent_id, options) => children(ctx, parent_id, options),
     files: (directory_id, options) => directory_files(ctx, directory_id, options)
@@ -2363,11 +2498,11 @@ function directories_wiki(ctx) {
 function get4(ctx, id) {
   return err.or_throw(directories_exports.by_id(ctx, id)) ?? null;
 }
-function search7(ctx, options) {
+function search11(ctx, options) {
   return err.or_throw(directories_exports.search(ctx, options));
 }
 function set_description3(ctx, id, description) {
-  err.or_throw(directories_exports.update(ctx, id, { description }));
+  err.or_throw(directories_exports.update(ctx, id, { description, state: "ready", error: null }));
 }
 function children(ctx, parent_id, options = {}) {
   let child_directories = err.or_throw(directories_exports.search(ctx, { select: options.select, where: { parent_id }, limit: 1e4 }));
@@ -2410,7 +2545,7 @@ function directory_files(ctx, directory_id, options = {}) {
 function dependencies_wiki(ctx) {
   return {
     get: (id) => get5(ctx, id),
-    search: (options) => search8(ctx, options),
+    search: (options) => search12(ctx, options),
     set_description: (id, description) => set_description4(ctx, id, description),
     used_by_file: (file_id, options) => used_by_file2(ctx, file_id, options),
     used_by_symbol: (symbol_id, options) => used_by_symbol2(ctx, symbol_id, options)
@@ -2419,7 +2554,7 @@ function dependencies_wiki(ctx) {
 function get5(ctx, id) {
   return err.or_throw(external_dependencies_exports.by_id(ctx, id)) ?? null;
 }
-function search8(ctx, options) {
+function search12(ctx, options) {
   return err.or_throw(external_dependencies_exports.search(ctx, options));
 }
 function set_description4(ctx, id, description) {
@@ -2432,13 +2567,88 @@ function used_by_symbol2(ctx, symbol_id, options) {
   return err.or_throw(external_dependencies_exports.used_by_symbol(ctx, symbol_id, options?.select));
 }
 
+// src/to_describe.ts
+function to_describe(ctx, limit) {
+  const dependencies_count = err.or_throw(external_dependencies_exports.count(ctx, { state: "to_describe" }));
+  if (dependencies_count > 0) return { type: "dependencies", items: dependencies_to_describe(ctx, limit) };
+  const symbols_count = err.or_throw(symbols_exports.count(ctx, { state: "to_describe" }));
+  if (symbols_count > 0) return { type: "symbols", items: symbols_to_describe(ctx, limit) };
+  const pending_symbols_count = err.or_throw(symbols_exports.count(ctx, { state: "to_link" }));
+  if (pending_symbols_count > 0) throw err.new("could_not_describe_files_due_to_pending_symbols", { count: pending_symbols_count });
+  const files_count = err.or_throw(files_exports.count(ctx, { state: "to_describe" }));
+  if (files_count > 0) return { type: "files", items: files_to_describe(ctx, limit) };
+  const pending_files_count = err.or_throw(files_exports.count(ctx, { state: "to_scan" }));
+  if (pending_files_count > 0) throw err.new("could_not_describe_directories_due_to_pending_files", { count: pending_files_count });
+  const directories_count = err.or_throw(directories_exports.count(ctx, { state: "to_describe" }));
+  if (directories_count > 0) return { type: "directories", items: directories_to_describe(ctx, limit) };
+  return { type: "none" };
+}
+function dependencies_to_describe(ctx, limit) {
+  const candidates = err.or_throw(
+    external_dependencies_exports.search(ctx, {
+      where: { state: "to_describe" },
+      select: ["id", "package", "name"],
+      limit: 1e5
+    })
+  );
+  candidates.sort((a, b) => {
+    if (a.package !== b.package) return a.package.localeCompare(b.package);
+    return (a.name || "").localeCompare(b.name || "");
+  });
+  const ids = candidates.slice(0, limit).map((dep) => dep.id);
+  const items = err.or_throw(external_dependencies_exports.by_ids(ctx, ids));
+  const by_id5 = new Map(items.map((item) => [item.id, item]));
+  return ids.map((id) => by_id5.get(id)).filter((item) => !!item);
+}
+function symbols_to_describe(ctx, limit) {
+  const candidates = err.or_throw(symbols_exports.search(ctx, { where: { state: "to_describe" }, select: ["id", "text"], limit: 1e5 }));
+  const counts2 = {};
+  for (const symbol of candidates) {
+    counts2[symbol.id] = {
+      length: symbol.text?.length ?? 0,
+      missing_external: err.or_throw(symbol_external_links_exports.count_pending_deps(ctx, symbol.id)),
+      missing_internal: err.or_throw(symbol_internal_links_exports.count(ctx, { from_symbol_id: symbol.id, state: "pending" }))
+    };
+  }
+  candidates.sort((x, y) => {
+    const a = counts2[x.id];
+    const b = counts2[y.id];
+    if (!a || !b) return 0;
+    if (a.missing_internal !== b.missing_internal) return a.missing_internal - b.missing_internal;
+    if (a.missing_external !== b.missing_external) return a.missing_external - b.missing_external;
+    return a.length - b.length;
+  });
+  const ids = candidates.slice(0, limit).map((symbol) => symbol.id);
+  const items = err.or_throw(symbols_exports.by_ids(ctx, ids));
+  const by_id5 = new Map(items.map((item) => [item.id, item]));
+  return ids.map((id) => by_id5.get(id)).filter((item) => !!item);
+}
+function files_to_describe(ctx, limit) {
+  return err.or_throw(files_exports.by_state(ctx, "to_describe", limit));
+}
+function directories_to_describe(ctx, limit) {
+  const candidates = err.or_throw(
+    directories_exports.search(ctx, {
+      where: { state: "to_describe" },
+      select: ["id", "path"],
+      limit: 1e5
+    })
+  );
+  candidates.sort((a, b) => b.path.split("/").length - a.path.split("/").length);
+  const ids = candidates.slice(0, limit).map((dir) => dir.id);
+  const items = err.or_throw(directories_exports.by_ids(ctx, ids));
+  const by_id5 = new Map(items.map((item) => [item.id, item]));
+  return ids.map((id) => by_id5.get(id)).filter((item) => !!item);
+}
+
 // src/index.ts
 async function create(config) {
   const ctx = await context_from_config(config);
   return {
     config,
     update: () => update6(ctx),
-    counts: () => err.or_throw(counts(ctx)),
+    counts: () => counts(ctx),
+    to_describe: (limit) => to_describe(ctx, limit),
     files: files_wiki(ctx),
     symbols: symbols_wiki(ctx),
     directories: directories_wiki(ctx),
@@ -2458,7 +2668,8 @@ async function load(db_path) {
   return {
     config,
     update: () => update6(ctx),
-    counts: () => err.or_throw(counts(ctx)),
+    counts: () => counts(ctx),
+    to_describe: (limit) => to_describe(ctx, limit),
     files: files_wiki(ctx),
     symbols: symbols_wiki(ctx),
     directories: directories_wiki(ctx),