knodin 0.7.6 → 0.8.2

package/dist/src/cli-args.js

@@ -0,0 +1,292 @@
+/**
+ * CLI argument & repo-target resolution for the `knodin` CLI (R19).
+ *
+ * The MCP gateway takes an explicit `repoPath`; the CLI historically fell back
+ * to `process.cwd()` with no equivalent flag, so `knodin index /other/repo` from
+ * the wrong cwd silently indexed nothing and exited 0. These pure helpers give
+ * the CLI one unambiguous way to target a repo (`--repo`) and make every no-op
+ * fail loudly. Kept side-effect-free (only stat the filesystem) so bin/cli.ts is
+ * a thin caller and the logic is unit-testable without an engine or database.
+ */
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+const GLOBAL_VALUE_FLAGS = new Set([
+    "--identity",
+    "--file",
+    "--kind",
+    "--to-identity",
+    "--to-file",
+    "--to-kind",
+    "--bytes",
+    "--tokens",
+    "--items",
+    "--impact-mode",
+    "--direction",
+    "--depth",
+    "--relations",
+    "--min-confidence",
+    "--limit",
+]);
+const GLOBAL_BOOLEAN_FLAGS = new Set(["--exclude-tests", "--data-flow", "--json"]);
+/**
+ * Command-scoped flags that take a value. These are NOT global — they are not
+ * hoisted or reordered — but their value must never be mistaken for a
+ * positional path. `knodin index --sarif results.sarif` asks to import that log,
+ * not to index the log as a source file.
+ */
+const COMMAND_VALUE_FLAGS = new Set([
+    "--scip",
+    "--scip-max-bytes",
+    "--scip-max-files",
+    "--scip-max-facts",
+    "--scip-timeout-ms",
+    "--sarif",
+    "--sarif-max-bytes",
+    "--sarif-max-findings",
+    "--sarif-timeout-ms",
+]);
+const isDir = (p) => {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+const RUNTIME_MODULE_FLAGS = new Set([
+    "--import",
+    "--loader",
+    "--experimental-loader",
+    "--require",
+    "-r",
+]);
+function resolveRuntimeModuleReference(value, cwd, resolveModule) {
+    if (path.isAbsolute(value) || /^[a-zA-Z][a-zA-Z\d+.-]*:/.test(value))
+        return value;
+    if (value.startsWith("."))
+        return path.resolve(cwd, value);
+    return resolveModule(value, cwd);
+}
+/**
+ * Reconstruct the executable command that launched this CLI. Source-checkout
+ * invocations need loader arguments such as `node --import tsx`; dropping
+ * `execArgv` creates a background hook that exists but cannot start. Bare
+ * loader names are resolved now because the hook later runs from another repo.
+ */
+export function resolveCliRuntimeCommand(runtime, resolveModule = (specifier, cwd) => createRequire(path.join(cwd, "package.json")).resolve(specifier)) {
+    const entry = runtime.argv[1];
+    if (!entry)
+        throw new Error("knodin: CLI entry path is unavailable");
+    const cwd = runtime.cwd();
+    const runtimeArguments = [];
+    for (let index = 0; index < runtime.execArgv.length; index++) {
+        const argument = runtime.execArgv[index];
+        if (RUNTIME_MODULE_FLAGS.has(argument)) {
+            const value = runtime.execArgv[index + 1];
+            if (!value)
+                throw new Error(`knodin: ${argument} requires a runtime module`);
+            runtimeArguments.push(argument, resolveRuntimeModuleReference(value, cwd, resolveModule));
+            index++;
+            continue;
+        }
+        const equalsFlag = [...RUNTIME_MODULE_FLAGS].find((flag) => argument.startsWith(`${flag}=`));
+        if (equalsFlag) {
+            const value = argument.slice(equalsFlag.length + 1);
+            if (!value)
+                throw new Error(`knodin: ${equalsFlag} requires a runtime module`);
+            runtimeArguments.push(`${equalsFlag}=${resolveRuntimeModuleReference(value, cwd, resolveModule)}`);
+            continue;
+        }
+        runtimeArguments.push(argument);
+    }
+    return [path.resolve(cwd, runtime.execPath), ...runtimeArguments, path.resolve(cwd, entry)];
+}
+/**
+ * Pull a global `--repo <path>` / `--repo=<path>` out of an argv slice and
+ * move any other documented global flags before the subcommand to immediately
+ * after it. This preserves the existing command parsers while accepting both
+ * conventional `knodin --file x explain y` and `knodin explain y --file x`.
+ */
+export function extractRepoFlag(argv) {
+    const rest = [];
+    const leadingGlobalOptions = [];
+    let repoFlag;
+    let commandSeen = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--repo") {
+            repoFlag = argv[i + 1] ?? "";
+            i++; // consume the value
+        }
+        else if (a.startsWith("--repo=")) {
+            repoFlag = a.slice("--repo=".length);
+        }
+        else if (!commandSeen && GLOBAL_VALUE_FLAGS.has(a)) {
+            leadingGlobalOptions.push(a);
+            if (argv[i + 1] !== undefined)
+                leadingGlobalOptions.push(argv[++i]);
+        }
+        else if (!commandSeen && GLOBAL_BOOLEAN_FLAGS.has(a)) {
+            leadingGlobalOptions.push(a);
+        }
+        else {
+            rest.push(a);
+            commandSeen = true;
+        }
+    }
+    rest.push(...leadingGlobalOptions);
+    return { repoFlag, rest };
+}
+/** Return positional arguments without mistaking recognized option values for paths. */
+export function extractPositionals(args) {
+    const positionals = [];
+    for (let index = 0; index < args.length; index++) {
+        const argument = args[index];
+        if (argument.startsWith("--")) {
+            if (!argument.includes("=") &&
+                (GLOBAL_VALUE_FLAGS.has(argument) || COMMAND_VALUE_FLAGS.has(argument)))
+                index++;
+            continue;
+        }
+        positionals.push(argument);
+    }
+    return positionals;
+}
+/**
+ * Resolve the target repo: an explicit `--repo` (validated as an existing
+ * directory) wins over `cwd`. An absent flag falls back to `cwd`.
+ */
+export function resolveRepo(repoFlag, cwd) {
+    if (repoFlag === undefined)
+        return { ok: true, repo: cwd };
+    if (repoFlag === "")
+        return { ok: false, error: "knodin: --repo requires a <path>" };
+    const repo = path.resolve(cwd, repoFlag);
+    if (!fs.existsSync(repo)) {
+        return { ok: false, error: `knodin: --repo path does not exist: ${repo}` };
+    }
+    if (!isDir(repo)) {
+        return { ok: false, error: `knodin: --repo path is not a directory: ${repo}` };
+    }
+    return { ok: true, repo };
+}
+/**
+ * Decide what `knodin index [positionals...]` actually targets, closing the
+ * silent-no-op hole:
+ *   - a lone directory positional with no `--repo` IS the repo (full reindex) —
+ *     this is the observed-bug fix: `knodin index /other/repo` now indexes it;
+ *   - any other directory positional is rejected, pointing at `--repo`;
+ *   - file positionals resolving outside the target repo are rejected loudly;
+ *   - otherwise the positionals are files to index within the resolved repo.
+ */
+export function planIndex(repoFlag, positionals, cwd) {
+    // Case A: no --repo and a single directory positional => that directory is
+    // the repo to index, not a file. Absorb it as the target.
+    if (repoFlag === undefined && positionals.length === 1) {
+        const abs = path.resolve(cwd, positionals[0]);
+        if (isDir(abs)) {
+            return { ok: true, repo: abs, files: undefined };
+        }
+    }
+    const resolved = resolveRepo(repoFlag, cwd);
+    if (!resolved.ok)
+        return resolved;
+    const repo = resolved.repo;
+    if (positionals.length === 0) {
+        return { ok: true, repo, files: undefined }; // full reindex
+    }
+    // Case B: positionals are files. Validate each is a within-repo non-directory.
+    const rejectedDirs = [];
+    const rejectedOutside = [];
+    const files = [];
+    for (const p of positionals) {
+        const abs = path.resolve(repo, p);
+        const rel = path.relative(repo, abs);
+        if (rel === "" || rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+            rejectedOutside.push(p);
+            continue;
+        }
+        if (isDir(abs)) {
+            rejectedDirs.push(p);
+            continue;
+        }
+        files.push(p);
+    }
+    if (rejectedOutside.length > 0 || rejectedDirs.length > 0) {
+        const parts = [];
+        if (rejectedOutside.length > 0) {
+            parts.push(`outside repo (${rejectedOutside.join(", ")})`);
+        }
+        if (rejectedDirs.length > 0) {
+            const hint = repoFlag === undefined
+                ? "use --repo to index a whole repo"
+                : "pass files, not directories, alongside --repo";
+            parts.push(`directories — ${hint} (${rejectedDirs.join(", ")})`);
+        }
+        return {
+            ok: false,
+            error: `knodin index: refusing to index against ${repo}; rejected ${parts.join("; ")}`,
+        };
+    }
+    return { ok: true, repo, files };
+}
+/**
+ * Guard against reporting success for a no-op: an index run that touched zero
+ * files must exit non-zero with a diagnostic naming the repo it actually used.
+ */
+export function checkIndexed(indexed, repo) {
+    if (!indexed || indexed.length === 0) {
+        return { ok: false, error: `knodin index: indexed 0 files in ${repo} (nothing matched)` };
+    }
+    return { ok: true };
+}
+/** Pure parser for `knodin review`, shared by the executable and CLI contract tests. */
+export function parseReviewArgs(args) {
+    const value = (flag) => {
+        const index = args.indexOf(flag);
+        if (index < 0)
+            return undefined;
+        const candidate = args[index + 1];
+        if (!candidate || candidate.startsWith("--")) {
+            throw new Error(`knodin review: ${flag} requires a value`);
+        }
+        return candidate;
+    };
+    const rawScope = value("--scope");
+    const scopes = ["unstaged", "staged", "all", "compare"];
+    if (rawScope && !scopes.includes(rawScope)) {
+        throw new Error(`invalid review scope: ${rawScope}`);
+    }
+    const optionValues = new Set([
+        ...GLOBAL_VALUE_FLAGS,
+        "--scope",
+        "--from",
+        "--to",
+        "--files",
+        "--scip",
+    ]);
+    const positionals = args.filter((arg, index) => {
+        if (arg.startsWith("--"))
+            return false;
+        return index === 0 || !optionValues.has(args[index - 1]);
+    });
+    const filesValue = value("--files");
+    const files = filesValue
+        ?.split(",")
+        .map((file) => file.trim())
+        .filter(Boolean);
+    if (filesValue !== undefined && files?.length === 0) {
+        throw new Error("knodin review: --files requires at least one repo-relative path");
+    }
+    return {
+        base: positionals.find((item) => item !== "minimal") ?? "HEAD~1",
+        detailLevel: positionals.includes("minimal") ? "minimal" : "standard",
+        options: {
+            scope: rawScope,
+            from: value("--from"),
+            to: value("--to"),
+            files,
+        },
+    };
+}