refactor(cli): improve index jobs and query coverage UX

packages/cli/src/args/archive-index.test.ts

@@ -28,6 +28,30 @@ describe("cli/args/archive index", () => {
       help: false,
       kind: "archive-index",
     });
+    expect(
+      parseCLIArguments([
+        "wikg:///tmp/book.wikg/index",
+        "sync",
+        "--jsonl",
+        "--skip-unindexed",
+      ]),
+    ).toStrictEqual({
+      args: {
+        action: "sync",
+        archivePath: "/tmp/book.wikg",
+        jsonl: true,
+        skipUnindexed: true,
+      },
+      help: false,
+      kind: "archive-index",
+    });
+    expect(() =>
+      parseCLIArguments([
+        "wikg:///tmp/book.wikg/index",
+        "clean",
+        "--skip-unindexed",
+      ]),
+    ).toThrow("The `clean` command does not support --skip-unindexed.");
     expect(() =>
       parseCLIArguments([
         "wikg:///tmp/book.wikg/index",

packages/cli/src/args/archive.test.ts

@@ -292,6 +292,24 @@ describe("cli/args/archive", () => {
       help: false,
       kind: "archive",
     });
+    expect(
+      parseCLIArguments([
+        "wikg://lib",
+        "--query",
+        "memory",
+        "--skip-unindexed",
+      ]),
+    ).toStrictEqual({
+      args: {
+        action: "search",
+        archivePath: "wikg://lib",
+        format: "text",
+        query: "memory",
+        skipUnindexed: true,
+      },
+      help: false,
+      kind: "archive",
+    });
 
     expect(
       parseCLIArguments([
@@ -448,6 +466,26 @@ describe("cli/args/archive", () => {
       help: false,
       kind: "archive",
     });
+    expect(
+      parseCLIArguments([
+        "wikg://lib/entity/Q23",
+        "evidence",
+        "--query",
+        "memory",
+        "--skip-unindexed",
+      ]),
+    ).toStrictEqual({
+      args: {
+        action: "evidence",
+        archivePath: "wikg://lib/entity/Q23",
+        format: "text",
+        objectId: "wikg://lib/entity/Q23",
+        query: "memory",
+        skipUnindexed: true,
+      },
+      help: false,
+      kind: "archive",
+    });
 
     expect(
       parseCLIArguments(["wikg://lib/entity/Q23", "related", "--cursor", "4"]),
@@ -462,6 +500,26 @@ describe("cli/args/archive", () => {
       help: false,
       kind: "archive",
     });
+    expect(
+      parseCLIArguments([
+        "wikg://lib/entity/Q23",
+        "related",
+        "--query",
+        "memory",
+        "--skip-unindexed",
+      ]),
+    ).toStrictEqual({
+      args: {
+        action: "related",
+        archivePath: "wikg://lib/entity/Q23",
+        format: "text",
+        objectId: "wikg://lib/entity/Q23",
+        query: "memory",
+        skipUnindexed: true,
+      },
+      help: false,
+      kind: "archive",
+    });
 
     expect(
       parseCLIArguments(["wikg://lib/entity/Q23", "pack", "--budget", "2000"]),
@@ -576,6 +634,26 @@ describe("cli/args/archive", () => {
       help: false,
       kind: "archive",
     });
+    expect(
+      parseCLIArguments([
+        "wikg://book.wikg/entity/Q1",
+        "related",
+        "--query",
+        "agents",
+        "--skip-unindexed",
+      ]),
+    ).toStrictEqual({
+      args: {
+        action: "related",
+        archivePath: "wikg://book.wikg/entity/Q1",
+        format: "text",
+        objectId: "wikg://book.wikg/entity/Q1",
+        query: "agents",
+        skipUnindexed: true,
+      },
+      help: false,
+      kind: "archive",
+    });
 
     expect(
       parseCLIArguments([
@@ -619,6 +697,25 @@ describe("cli/args/archive", () => {
       kind: "archive",
     });
 
+    expect(
+      parseCLIArguments([
+        "wikg:///Users/me/book.wikg",
+        "--query",
+        "RAG",
+        "--skip-unindexed",
+      ]),
+    ).toStrictEqual({
+      args: {
+        action: "search",
+        archivePath: "wikg:///Users/me/book.wikg",
+        format: "text",
+        query: "RAG",
+        skipUnindexed: true,
+      },
+      help: false,
+      kind: "archive",
+    });
+
     expect(
       parseCLIArguments([
         "wikg:///Users/me/book.wikg",
@@ -713,6 +810,26 @@ describe("cli/args/archive", () => {
       help: false,
       kind: "archive",
     });
+    expect(
+      parseCLIArguments([
+        "wikg://book.wikg/triple/Q1/mentions/Q2",
+        "evidence",
+        "--query",
+        "agents",
+        "--skip-unindexed",
+      ]),
+    ).toStrictEqual({
+      args: {
+        action: "evidence",
+        archivePath: "wikg://book.wikg/triple/Q1/mentions/Q2",
+        format: "text",
+        objectId: "wikg://book.wikg/triple/Q1/mentions/Q2",
+        query: "agents",
+        skipUnindexed: true,
+      },
+      help: false,
+      kind: "archive",
+    });
 
     expect(
       parseCLIArguments([
@@ -1010,6 +1127,24 @@ describe("cli/args/archive", () => {
       help: false,
       kind: "archive",
     });
+    expect(
+      parseCLIArguments([
+        "wikg://book.wikg/chapter/part",
+        "--query",
+        "agent",
+        "--skip-unindexed",
+      ]),
+    ).toStrictEqual({
+      args: {
+        action: "search",
+        archivePath: `wikg://${archivePath}/chapter/part`,
+        format: "text",
+        query: "agent",
+        skipUnindexed: true,
+      },
+      help: false,
+      kind: "archive",
+    });
     expect(() =>
       parseCLIArguments(["wikg://book.wikg/chapter/part", "get"]),
     ).toThrow("This command form is not available.");

packages/cli/src/args/archive.ts

@@ -74,6 +74,8 @@ export function parseArchiveArguments(
     );
   }
 
+  rejectNonQuerySkipUnindexedFlag(action, values, helpRoute);
+
   switch (action) {
     case "create": {
       rejectArchiveExtraPositionals(action, positionals, 1, helpRoute);
@@ -267,6 +269,7 @@ export function parseArchiveArguments(
                 ),
               }),
           query,
+          ...(values["skip-unindexed"] === true ? { skipUnindexed: true } : {}),
           ...(options.defaultKinds === undefined
             ? {}
             : { kinds: options.defaultKinds }),
@@ -405,6 +408,7 @@ export function parseArchiveArguments(
           objectId: archivePath,
           ...(values.query === undefined ? {} : { query: values.query }),
           ...(values.reverse === true ? { reverse: true } : {}),
+          ...(values["skip-unindexed"] === true ? { skipUnindexed: true } : {}),
           ...(relatedTarget === "entity"
             ? parseRelatedRoleFlag(values.role, helpRoute)
             : {}),
@@ -452,6 +456,7 @@ export function parseArchiveArguments(
           objectId: archivePath,
           ...(values.query === undefined ? {} : { query: values.query }),
           ...(values.reverse === true ? { reverse: true } : {}),
+          ...(values["skip-unindexed"] === true ? { skipUnindexed: true } : {}),
         },
         help: false,
         kind: "archive",
@@ -551,3 +556,27 @@ function rejectNonChapterDepthFlag(
 
   rejectArchiveFlag(action, "--depth", depth, helpRoute);
 }
+
+function rejectNonQuerySkipUnindexedFlag(
+  action: CLIArchiveAction,
+  values: ArchiveArgumentValues,
+  helpRoute: string,
+): void {
+  if (values["skip-unindexed"] !== true) {
+    return;
+  }
+  if (
+    action === "search" ||
+    ((action === "related" || action === "evidence") &&
+      values.query !== undefined)
+  ) {
+    return;
+  }
+
+  rejectArchiveBooleanFlag(
+    action,
+    "--skip-unindexed",
+    values["skip-unindexed"],
+    helpRoute,
+  );
+}

packages/cli/src/args/gc.test.ts

@@ -43,5 +43,11 @@ describe("cli/args/gc", () => {
     expect(() => parseCLIArguments(["gc", "--jsonl"])).toThrow(
       "The `gc` command does not support --jsonl",
     );
+    expect(() => parseCLIArguments(["gc", "--skip-unindexed"])).toThrow(
+      "The current command does not support --skip-unindexed.",
+    );
+    expect(() => parseCLIArguments(["transform", "--skip-unindexed"])).toThrow(
+      "The current command does not support --skip-unindexed.",
+    );
   });
 });

packages/cli/src/args/help.test.ts

@@ -487,6 +487,7 @@ describe("cli/args/help", () => {
       "Do not pass a bare filesystem path as a command target.",
     );
     expect(uriHelpText).toContain('wg <archive-uri> --query "term"');
+    expect(uriHelpText).toContain("--skip-unindexed");
     expect(uriHelpText).toContain(
       String.raw`C:\Users\me\book.wikg -> wikg://C:/Users/me/book.wikg`,
     );
@@ -536,6 +537,13 @@ describe("cli/args/help", () => {
     expect(
       renderUriPredicateHelpText("index-object", "sync", "wikg://lib/index"),
     ).toContain("Sync this library index cache");
+    expect(
+      renderUriPredicateHelpText(
+        "index-object",
+        "sync",
+        "wikg://book.wikg/index",
+      ),
+    ).toContain("[--skip-unindexed]");
     expect(
       renderUriPredicateHelpText("index-object", "sync", "wikg://lib/index"),
     ).not.toContain(
@@ -813,6 +821,7 @@ describe("cli/args/help", () => {
     ).toThrow("does not support `list`");
     expect(scopeHelpText).toContain("wg wikg://lib [--json]");
     expect(scopeHelpText).toContain("wg wikg://lib --query <query>");
+    expect(scopeHelpText).toContain("--skip-unindexed");
     expect(scopeHelpText).toContain("searches library-wide objects");
     expect(scopeHelpText).not.toContain("searches archive members");
     expect(scopeHelpText).not.toContain("broad library index search");
@@ -943,6 +952,24 @@ describe("cli/args/help", () => {
     expect(archiveMemberInspectHelp.helpText).toContain(
       "not a library-level health report",
     );
+    const relatedHelpText = renderUriPredicateHelpText(
+      "entity-object",
+      "related",
+      "wikg://book.wikg/entity/Q23",
+    );
+    const evidenceHelpText = renderUriPredicateHelpText(
+      "entity-object",
+      "evidence",
+      "wikg://book.wikg/entity/Q23",
+    );
+    expect(relatedHelpText).toContain("[--skip-unindexed]");
+    expect(relatedHelpText).toContain(
+      "Add `--skip-unindexed` only with `--query`",
+    );
+    expect(evidenceHelpText).toContain("[--skip-unindexed]");
+    expect(evidenceHelpText).toContain(
+      "Add `--skip-unindexed` only with `--query`",
+    );
     const registryHelpText = renderLibraryUriHelpText("wikg://lib/registry", {
       isDefault: true,
       kind: "registry",

packages/cli/src/args/parse.ts

@@ -169,6 +169,9 @@ export function parseCLIArguments(
       reverse: {
         type: "boolean",
       },
+      "skip-unindexed": {
+        type: "boolean",
+      },
       stage: {
         type: "string",
       },
@@ -233,6 +236,7 @@ export function parseCLIArguments(
 
   rejectNonGcForceFlag(positionals, values);
   rejectNonCreateReplaceFlag(positionals, values);
+  rejectNonWikiGraphSkipUnindexedFlag(positionals, values);
   rejectUnsupportedIndexesFlag(values.indexes);
 
   if (values.version === true) {
@@ -360,3 +364,27 @@ function rejectUnsupportedIndexesFlag(value: string | undefined): void {
     ),
   );
 }
+
+function rejectNonWikiGraphSkipUnindexedFlag(
+  positionals: readonly string[],
+  values: { readonly "skip-unindexed"?: boolean },
+): void {
+  if (values["skip-unindexed"] !== true) {
+    return;
+  }
+
+  const command = positionals[0];
+  if (
+    command !== undefined &&
+    (isWikiGraphUri(command) || isWikiGraphLibraryUri(command))
+  ) {
+    return;
+  }
+
+  throw new Error(
+    withHelpRoute(
+      "The current command does not support --skip-unindexed.",
+      CLI_HELP_ROUTES.root,
+    ),
+  );
+}