@webneat/codewiki 0.0.2 → 0.0.5

package/dist/index.cjs

@@ -39,10 +39,9 @@ module.exports = __toCommonJS(src_exports);
 
 // src/internals/context.ts
 var import_typescript = __toESM(require("typescript"), 1);
-var import_url = require("url");
 var import_better_sqlite3 = __toESM(require("better-sqlite3"), 1);
 var import_promises2 = require("fs/promises");
-var import_path2 = __toESM(require("path"), 1);
+var import_node_path2 = __toESM(require("path"), 1);
 var import_better_sqlite32 = require("drizzle-orm/better-sqlite3");
 
 // ../errors/dist/index.js
@@ -106,6 +105,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}`,
@@ -118,6 +118,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}`,
@@ -127,7 +129,7 @@ var err = index_default({
 
 // src/db/migrate.ts
 var import_promises = require("fs/promises");
-var import_path = require("path");
+var import_node_path = require("path");
 var import_drizzle_orm2 = require("drizzle-orm");
 
 // src/db/schema.ts
@@ -453,7 +455,7 @@ async function get_applied_migration_names({ db: db6 }) {
   return new Set(applied.map((x) => x.name));
 }
 async function apply_migration({ sqlite, migrations_path }, filename) {
-  const file_path = (0, import_path.join)(migrations_path, filename);
+  const file_path = (0, import_node_path.join)(migrations_path, filename);
   const queries = await (0, import_promises.readFile)(file_path, "utf-8");
   sqlite.transaction(() => {
     sqlite.exec(queries);
@@ -478,6 +480,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: (0, import_drizzle_orm3.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];
@@ -529,8 +534,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,
@@ -545,12 +552,16 @@ __export(files_exports, {
 var import_drizzle_orm5 = require("drizzle-orm");
 
 // src/internals/utils.ts
-var import_fs = require("fs");
+var import_node_fs = require("fs");
 var parse_json = err.safe(JSON.parse, (reason, text2) => err.new("invalid_json", { reason, text: text2 }));
 var read_file = err.safe(
-  (path6) => (0, import_fs.readFileSync)(path6, "utf-8"),
+  (path6) => (0, import_node_fs.readFileSync)(path6, "utf-8"),
   (reason, path6) => err.new("could_not_read_file", { path: path6, reason })
 );
+var file_stat = err.safe(
+  (path6) => (0, import_node_fs.statSync)(path6),
+  (reason, path6) => err.new("file_stat_error", { path: path6, reason })
+);
 function group_by_unique(items, key) {
   const groups = {};
   for (const item of items) {
@@ -615,6 +626,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"];
@@ -622,15 +661,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((0, import_drizzle_orm5.eq)(files.id, id)).get());
+var by_ids = safe_query(
+  "files.by_ids",
+  (ctx, ids) => ctx.db.select().from(files).where((0, import_drizzle_orm5.inArray)(files.id, ids)).all()
+);
 var by_path = safe_query(
   "files.by_path",
   (ctx, path6) => ctx.db.select().from(files).where((0, import_drizzle_orm5.eq)(files.path, path6)).get()
 );
-var by_state = safe_query(
-  "files.by_state",
-  (ctx, state) => ctx.db.select().from(files).where((0, import_drizzle_orm5.eq)(files.state, state)).all()
-);
+var by_state = safe_query("files.by_state", (ctx, state, limit) => {
+  let query = ctx.db.select().from(files).where((0, import_drizzle_orm5.eq)(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",
@@ -672,8 +719,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((0, import_drizzle_orm5.eq)(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((0, import_drizzle_orm5.eq)(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((0, import_drizzle_orm5.inArray)(files.id, file_ids)).all();
   }
@@ -704,8 +751,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,
@@ -716,6 +765,10 @@ var by_id2 = safe_query(
   "directories.by_id",
   (ctx, id) => ctx.db.select().from(directories).where((0, import_drizzle_orm6.eq)(directories.id, id)).get()
 );
+var by_ids2 = safe_query(
+  "directories.by_ids",
+  (ctx, ids) => ctx.db.select().from(directories).where((0, import_drizzle_orm6.inArray)(directories.id, ids)).all()
+);
 var by_path2 = safe_query(
   "directories.by_path",
   (ctx, path6) => ctx.db.select().from(directories).where((0, import_drizzle_orm6.eq)(directories.path, path6)).get()
@@ -743,6 +796,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 = {};
@@ -750,11 +806,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
 });
 var import_drizzle_orm7 = require("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: (0, import_drizzle_orm7.count)() }).from(imports).innerJoin(symbols, (0, import_drizzle_orm7.eq)(imports.symbol_id, symbols.id)).where((0, import_drizzle_orm7.and)((0, import_drizzle_orm7.eq)(imports.importer_file_id, file_id), (0, import_drizzle_orm7.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((0, import_drizzle_orm7.eq)(imports.exporter_file_id, exporter_file_id)).all()
@@ -784,13 +852,15 @@ __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
 });
@@ -817,6 +887,10 @@ var update4 = safe_query(
   (ctx, id, data) => ctx.db.update(symbols).set(data).where((0, import_drizzle_orm8.eq)(symbols.id, id)).run()
 );
 var by_id3 = safe_query("symbols.by_id", (ctx, id) => ctx.db.select().from(symbols).where((0, import_drizzle_orm8.eq)(symbols.id, id)).get());
+var by_ids3 = safe_query(
+  "symbols.by_ids",
+  (ctx, ids) => ctx.db.select().from(symbols).where((0, import_drizzle_orm8.inArray)(symbols.id, ids)).all()
+);
 var by_id_and_state3 = safe_query(
   "symbols.by_id_and_state",
   (ctx, params) => ctx.db.select().from(symbols).where((0, import_drizzle_orm8.and)((0, import_drizzle_orm8.eq)(symbols.id, params.id), (0, import_drizzle_orm8.eq)(symbols.state, params.state))).get()
@@ -827,8 +901,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",
@@ -866,11 +944,13 @@ 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
@@ -880,6 +960,10 @@ var by_id4 = safe_query(
   "external_dependencies.by_id",
   (ctx, id) => ctx.db.select().from(external_dependencies).where((0, import_drizzle_orm9.eq)(external_dependencies.id, id)).get()
 );
+var by_ids4 = safe_query(
+  "external_dependencies.by_ids",
+  (ctx, ids) => ctx.db.select().from(external_dependencies).where((0, import_drizzle_orm9.inArray)(external_dependencies.id, ids)).all()
+);
 var by_state5 = safe_query(
   "external_dependencies.by_state",
   (ctx, state) => ctx.db.select().from(external_dependencies).where((0, import_drizzle_orm9.eq)(external_dependencies.state, state)).all()
@@ -909,11 +993,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",
@@ -945,10 +1031,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
 });
 var import_drizzle_orm10 = require("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: (0, import_drizzle_orm10.count)() }).from(external_imports).innerJoin(external_dependencies, (0, import_drizzle_orm10.eq)(external_imports.external_dependency_id, external_dependencies.id)).where((0, import_drizzle_orm10.and)((0, import_drizzle_orm10.eq)(external_imports.file_id, file_id), (0, import_drizzle_orm10.ne)(external_dependencies.state, "ready"))).get()?.count ?? 0;
+});
 var insert_many3 = safe_query(
   "external_imports.insert_many",
   (ctx, values) => ctx.db.insert(external_imports).values(values).run()
@@ -983,11 +1081,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
 });
 var import_drizzle_orm11 = require("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);
+});
 var by_from_symbol = safe_query(
   "symbol_internal_links.by_from_symbol",
   (ctx, from_symbol_id) => ctx.db.query.symbol_internal_links.findMany({
@@ -1013,17 +1120,37 @@ 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((0, import_drizzle_orm11.eq)(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((0, import_drizzle_orm11.eq)(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
 });
 var import_drizzle_orm12 = require("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: (0, import_drizzle_orm12.count)() }).from(symbol_external_links).innerJoin(external_imports, (0, import_drizzle_orm12.eq)(symbol_external_links.external_import_id, external_imports.id)).where((0, import_drizzle_orm12.eq)(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: (0, import_drizzle_orm12.count)() }).from(symbol_external_links).innerJoin(external_imports, (0, import_drizzle_orm12.eq)(symbol_external_links.external_import_id, external_imports.id)).innerJoin(external_dependencies, (0, import_drizzle_orm12.eq)(external_imports.external_dependency_id, external_dependencies.id)).where((0, import_drizzle_orm12.and)((0, import_drizzle_orm12.eq)(symbol_external_links.symbol_id, symbol_id), (0, import_drizzle_orm12.ne)(external_dependencies.state, "ready"))).get()?.count ?? 0;
+});
 var by_symbol2 = safe_query(
   "symbol_external_links.by_symbol",
   (ctx, symbol_id) => ctx.db.select().from(symbol_external_links).where((0, import_drizzle_orm12.eq)(symbol_external_links.symbol_id, symbol_id)).all()
@@ -1046,19 +1173,18 @@ var del_by_symbol = safe_query(
 );
 
 // src/internals/context.ts
-var import_meta = {};
 async function create_context(sqlite, db6, config) {
-  const project_path = import_path2.default.resolve(config.project_path);
-  const currentDir = (0, import_path2.dirname)((0, import_url.fileURLToPath)(import_meta.url));
-  const migrations_path = currentDir.includes("/dist") ? (0, import_path2.join)(currentDir, "../migrations") : (0, import_path2.join)(currentDir, "../../migrations");
-  const tsconfig_path = (0, import_path2.join)(project_path, "tsconfig.json");
+  const project_path = import_node_path2.default.resolve(config.project_path);
+  const currentDir = __dirname;
+  const migrations_path = currentDir.includes("/dist") ? (0, import_node_path2.join)(currentDir, "../migrations") : (0, import_node_path2.join)(currentDir, "../../migrations");
+  const tsconfig_path = (0, import_node_path2.join)(project_path, "tsconfig.json");
   if (!import_typescript.default.sys.fileExists(tsconfig_path)) {
     throw err.new("file_not_found", { path: tsconfig_path });
   }
   const tsconfig = import_typescript.default.parseJsonConfigFileContent(import_typescript.default.readConfigFile(tsconfig_path, import_typescript.default.sys.readFile).config, import_typescript.default.sys, project_path);
   const program = import_typescript.default.createProgram({ rootNames: tsconfig.fileNames, options: tsconfig.options });
-  const package_json_path = config.package_json_path ?? import_path2.default.join(project_path, "package.json");
-  const node_modules_paths = config.node_modules_paths ?? [import_path2.default.join(project_path, "node_modules")];
+  const package_json_path = config.package_json_path ?? import_node_path2.default.join(project_path, "package.json");
+  const node_modules_paths = config.node_modules_paths ?? [import_node_path2.default.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);
@@ -1117,7 +1243,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 = import_path2.default.join(node_modules_path, package_name, "package.json");
+      const package_json_path = import_node_path2.default.join(node_modules_path, package_name, "package.json");
       const package_json = JSON.parse(await (0, import_promises2.readFile)(package_json_path, "utf-8"));
       const url = package_json.repository?.url || package_json.repository;
       if (typeof url === "string") {
@@ -1132,7 +1258,7 @@ async function get_github_repo(node_modules_paths, package_name) {
 }
 
 // src/update/track_changes.ts
-var import_path3 = __toESM(require("path"), 1);
+var import_node_path3 = __toESM(require("path"), 1);
 var import_typescript2 = require("typescript");
 var import_promises3 = require("fs/promises");
 
@@ -1143,9 +1269,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);
       }
     })
   );
@@ -1178,7 +1304,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 (!import_path3.default.resolve(file.fileName).startsWith(ctx.project_path)) continue;
+    if (!import_node_path3.default.resolve(file.fileName).startsWith(ctx.project_path)) continue;
     src_files.push(file);
   }
   return src_files;
@@ -1226,7 +1352,7 @@ async function changes(ctx, source_files, db_files) {
   return { created, updated, deleted };
 }
 function get_file_path(ctx, file) {
-  const absolute_path = import_path3.default.resolve(file.fileName);
+  const absolute_path = import_node_path3.default.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 });
 }
@@ -1234,10 +1360,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 = import_path3.default.dirname(file_path);
-  while (current !== import_path3.default.sep) {
+  let current = import_node_path3.default.dirname(file_path);
+  while (current !== import_node_path3.default.sep) {
     dirs.push(current);
-    current = import_path3.default.dirname(current);
+    current = import_node_path3.default.dirname(current);
   }
   dirs.push(current);
   return dirs.reverse();
@@ -1271,19 +1397,19 @@ async function sync_external_dependencies(ctx) {
 }
 
 // src/update/scan_files/scan_files.ts
-var import_path5 = __toESM(require("path"), 1);
+var import_node_path5 = __toESM(require("path"), 1);
 var import_typescript10 = __toESM(require("typescript"), 1);
 
 // src/update/scan_files/imports.ts
 var import_typescript4 = __toESM(require("typescript"), 1);
 
 // src/update/scan_files/common.ts
-var import_path4 = __toESM(require("path"), 1);
+var import_node_path4 = __toESM(require("path"), 1);
 var import_typescript3 = __toESM(require("typescript"), 1);
 function is_external_module(ctx, source_file, module_path) {
   const resolved = import_typescript3.default.resolveModuleName(module_path, source_file.fileName, ctx.program.getCompilerOptions(), import_typescript3.default.sys);
   if (!resolved.resolvedModule) return true;
-  const resolved_path = import_path4.default.resolve(resolved.resolvedModule.resolvedFileName);
+  const resolved_path = import_node_path4.default.resolve(resolved.resolvedModule.resolvedFileName);
   return !resolved_path.startsWith(ctx.project_path);
 }
 function has_export_modifier(node) {
@@ -1392,13 +1518,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 || !import_typescript4.default.isStringLiteral(node.moduleSpecifier)) return imports2;
+  if (!clause || !node.moduleSpecifier || !import_typescript4.default.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",
@@ -1408,7 +1534,7 @@ function extract_import(ctx, source_file, node, file_id) {
   }
   if (clause.namedBindings && import_typescript4.default.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,
@@ -1418,7 +1544,7 @@ function extract_import(ctx, source_file, node, file_id) {
     }
   }
   if (clause.namedBindings && import_typescript4.default.isNamespaceImport(clause.namedBindings)) {
-    imports2.push({
+    imports4.push({
       importer_file_id: file_id,
       exporter_file_id,
       name: "*",
@@ -1426,7 +1552,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];
@@ -1538,7 +1664,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, {
@@ -1551,9 +1677,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];
@@ -1858,32 +1984,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(import_path5.default.join(ctx.project_path, file_path));
+  const source_file = ctx.program.getSourceFile(import_node_path5.default.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);
       }
     }
     import_typescript10.default.forEachChild(node, find_dynamic_imports);
@@ -1896,24 +2022,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 (import_typescript10.default.isExportAssignment(node) && !node.isExportEquals) {
     symbols3.push({
       file_id,
@@ -1955,14 +2081,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) }));
   }
@@ -1978,7 +2104,7 @@ function link_import(ctx, import_) {
 }
 
 // src/update/link_symbols.ts
-var import_path6 = __toESM(require("path"), 1);
+var import_node_path6 = __toESM(require("path"), 1);
 var import_typescript11 = __toESM(require("typescript"), 1);
 async function link_symbols(ctx) {
   const symbols3 = err.or_throw(symbols_exports.by_state(ctx, "to_link"));
@@ -2004,7 +2130,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 = import_path6.default.join(ctx.project_path, file.path);
+  const file_path = import_node_path6.default.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);
@@ -2229,7 +2355,7 @@ async function update6(ctx) {
 
 // src/counts.ts
 var import_drizzle_orm13 = require("drizzle-orm");
-var counts = safe_query("counts", (ctx) => {
+function counts(ctx) {
   const symbol_counts = ctx.db.select({ state: symbols.state, count: (0, import_drizzle_orm13.count)() }).from(symbols).groupBy(symbols.state).all();
   const file_counts = ctx.db.select({ state: files.state, count: (0, import_drizzle_orm13.count)() }).from(files).groupBy(files.state).all();
   const dir_counts = ctx.db.select({ state: directories.state, count: (0, import_drizzle_orm13.count)() }).from(directories).groupBy(directories.state).all();
@@ -2240,7 +2366,7 @@ var counts = safe_query("counts", (ctx) => {
     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;
@@ -2256,7 +2382,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),
@@ -2266,11 +2392,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));
@@ -2322,7 +2448,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),
@@ -2332,11 +2458,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));
@@ -2388,7 +2515,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)
@@ -2397,11 +2524,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 }));
@@ -2444,7 +2571,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)
@@ -2453,7 +2580,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) {
@@ -2466,13 +2593,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),
@@ -2492,7 +2694,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),