docs-cache 0.4.3 → 0.5.1

package/dist/esm/cli/parse-args.mjs

@@ -0,0 +1,295 @@
+import process from "node:process";
+import cac from "cac";
+import { ExitCode } from "#cli/exit-code";
+const COMMANDS = [
+  "add",
+  "remove",
+  "sync",
+  "status",
+  "clean",
+  "clean-cache",
+  "prune",
+  "verify",
+  "init"
+];
+const ADD_ONLY_OPTIONS = /* @__PURE__ */ new Set([
+  "--source",
+  "--target",
+  "--target-dir",
+  "--id"
+]);
+const POSITIONAL_SKIP_OPTIONS = /* @__PURE__ */ new Set([
+  "--config",
+  "--cache-dir",
+  "--concurrency",
+  "--timeout-ms"
+]);
+const ADD_ONLY_OPTIONS_WITH_VALUES = /* @__PURE__ */ new Set([
+  "--id",
+  "--source",
+  "--target",
+  "--target-dir"
+]);
+const ADD_ENTRY_SKIP_OPTIONS = /* @__PURE__ */ new Set([
+  "--config",
+  "--cache-dir",
+  "--concurrency",
+  "--timeout-ms"
+]);
+const VALUE_FLAGS = /* @__PURE__ */ new Set([
+  ...POSITIONAL_SKIP_OPTIONS,
+  ...ADD_ONLY_OPTIONS_WITH_VALUES
+]);
+const getArgValue = (arg, next, flag) => {
+  const rawValue = arg === flag ? next : arg.slice(flag.length + 1);
+  if (!rawValue || rawValue.startsWith("-")) {
+    throw new Error(`${flag} expects a value.`);
+  }
+  return rawValue;
+};
+const addEntry = (state, repo) => {
+  state.entries.push({
+    repo,
+    ...state.pendingId ? { id: state.pendingId } : {}
+  });
+  state.lastIndex = state.entries.length - 1;
+  state.pendingId = null;
+  state.lastWasRepoAdded = true;
+};
+const applyPendingId = (state, value) => {
+  const canApply = state.lastWasRepoAdded && state.lastIndex !== -1 && state.entries[state.lastIndex]?.id === void 0 && state.pendingId === null;
+  if (!canApply) {
+    if (state.pendingId !== null) {
+      throw new Error("--id must be followed by a source.");
+    }
+    state.pendingId = value;
+    state.lastWasRepoAdded = false;
+    return;
+  }
+  state.entries[state.lastIndex].id = value;
+  state.lastWasRepoAdded = false;
+};
+const setTarget = (state, targetDir) => {
+  if (state.lastIndex === -1) {
+    throw new Error("--target must follow a --source entry.");
+  }
+  state.entries[state.lastIndex].targetDir = targetDir;
+  state.lastWasRepoAdded = false;
+};
+const findCommandIndex = (rawArgs) => {
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index];
+    if (arg.startsWith("--")) {
+      const [flag] = arg.split("=");
+      if (VALUE_FLAGS.has(flag) && !arg.includes("=")) {
+        index += 1;
+      }
+      continue;
+    }
+    return index;
+  }
+  return -1;
+};
+const parseAddEntries = (rawArgs) => {
+  const commandIndex = findCommandIndex(rawArgs);
+  const tail = commandIndex === -1 ? [] : rawArgs.slice(commandIndex + 1);
+  const state = {
+    entries: [],
+    lastIndex: -1,
+    pendingId: null,
+    lastWasRepoAdded: false
+  };
+  for (let index = 0; index < tail.length; index += 1) {
+    const arg = tail[index];
+    if (arg === "--id" || arg.startsWith("--id=")) {
+      const value = getArgValue(arg, tail[index + 1], "--id");
+      if (arg === "--id") {
+        index += 1;
+      }
+      applyPendingId(state, value);
+      continue;
+    }
+    if (arg === "--source" || arg.startsWith("--source=")) {
+      const value = getArgValue(arg, tail[index + 1], "--source");
+      addEntry(state, value);
+      if (arg === "--source") {
+        index += 1;
+      }
+      continue;
+    }
+    if (arg === "--target" || arg.startsWith("--target=")) {
+      const value = getArgValue(arg, tail[index + 1], "--target");
+      setTarget(state, value);
+      if (arg === "--target") {
+        index += 1;
+      }
+      continue;
+    }
+    if (arg === "--target-dir" || arg.startsWith("--target-dir=")) {
+      const value = getArgValue(arg, tail[index + 1], "--target-dir");
+      setTarget(state, value);
+      if (arg === "--target-dir") {
+        index += 1;
+      }
+      continue;
+    }
+    if (ADD_ENTRY_SKIP_OPTIONS.has(arg)) {
+      index += 1;
+      state.lastWasRepoAdded = false;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      state.lastWasRepoAdded = false;
+      continue;
+    }
+    addEntry(state, arg);
+  }
+  if (state.pendingId !== null) {
+    throw new Error("--id must be followed by a source.");
+  }
+  return state.entries;
+};
+const parsePositionals = (rawArgs) => {
+  const commandIndex = findCommandIndex(rawArgs);
+  const tail = commandIndex === -1 ? [] : rawArgs.slice(commandIndex + 1);
+  const positionals = [];
+  for (let index = 0; index < tail.length; index += 1) {
+    const arg = tail[index];
+    if (POSITIONAL_SKIP_OPTIONS.has(arg)) {
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      continue;
+    }
+    positionals.push(arg);
+  }
+  return positionals;
+};
+const assertAddOnlyOptions = (command, rawArgs) => {
+  if (command === "add") {
+    return;
+  }
+  for (const arg of rawArgs) {
+    if (ADD_ONLY_OPTIONS.has(arg)) {
+      throw new Error(`${arg} is only valid for add.`);
+    }
+    if (!arg.startsWith("--")) {
+      continue;
+    }
+    const [flag] = arg.split("=");
+    if (ADD_ONLY_OPTIONS_WITH_VALUES.has(flag)) {
+      throw new Error(`${flag} is only valid for add.`);
+    }
+  }
+};
+const buildOptions = (result) => {
+  const options = {
+    config: result.options.config,
+    cacheDir: result.options.cacheDir,
+    offline: Boolean(result.options.offline),
+    failOnMiss: Boolean(result.options.failOnMiss),
+    lockOnly: Boolean(result.options.lockOnly),
+    prune: Boolean(result.options.prune),
+    concurrency: result.options.concurrency ? Number(result.options.concurrency) : void 0,
+    json: Boolean(result.options.json),
+    timeoutMs: result.options.timeoutMs ? Number(result.options.timeoutMs) : void 0,
+    silent: Boolean(result.options.silent),
+    verbose: Boolean(result.options.verbose)
+  };
+  if (options.concurrency !== void 0 && options.concurrency < 1) {
+    throw new Error("--concurrency must be a positive number.");
+  }
+  if (options.concurrency !== void 0 && !Number.isFinite(options.concurrency)) {
+    throw new Error("--concurrency must be a positive number.");
+  }
+  if (options.timeoutMs !== void 0 && options.timeoutMs < 1) {
+    throw new Error("--timeout-ms must be a positive number.");
+  }
+  if (options.timeoutMs !== void 0 && !Number.isFinite(options.timeoutMs)) {
+    throw new Error("--timeout-ms must be a positive number.");
+  }
+  return options;
+};
+const getCommandFromArgs = (rawArgs) => {
+  const commandIndex = findCommandIndex(rawArgs);
+  const command = commandIndex === -1 ? void 0 : rawArgs[commandIndex];
+  if (command && !COMMANDS.includes(command)) {
+    throw new Error(`Unknown command '${command}'.`);
+  }
+  return command ?? null;
+};
+const getPositionals = (command, rawArgs, entries) => {
+  if (command === "add") {
+    const addEntries = entries ?? parseAddEntries(rawArgs);
+    return { positionals: addEntries.map((entry) => entry.repo), addEntries };
+  }
+  return { positionals: parsePositionals(rawArgs), addEntries: entries };
+};
+const buildParsedCommand = (command, options, positionals, addEntries) => {
+  switch (command) {
+    case "add":
+      return {
+        command: "add",
+        entries: addEntries ?? [],
+        options
+      };
+    case "remove":
+      return { command: "remove", ids: positionals, options };
+    case "sync":
+      return { command: "sync", options };
+    case "status":
+      return { command: "status", options };
+    case "clean":
+      return { command: "clean", options };
+    case "clean-cache":
+      return { command: "clean-cache", options };
+    case "prune":
+      return { command: "prune", options };
+    case "verify":
+      return { command: "verify", options };
+    case "init":
+      return { command: "init", options };
+    default:
+      return { command: null, options };
+  }
+};
+export const parseArgs = (argv = process.argv) => {
+  try {
+    const cli = cac("docs-cache");
+    cli.option("--config <path>", "Path to config file").option("--cache-dir <path>", "Override cache directory").option("--offline", "Disable network access").option("--fail-on-miss", "Fail when required sources are missing").option("--lock-only", "Update lock without materializing files").option("--prune", "Prune cache on remove").option("--concurrency <n>", "Concurrency limit").option("--json", "Output JSON").option("--timeout-ms <n>", "Network timeout in milliseconds").option("--silent", "Suppress non-error output").option("--verbose", "Enable verbose logging").help();
+    cli.command("add [repo...]", "Add sources to the config").option("--source <repo>", "Source repo").option("--target <dir>", "Target directory for source").option("--target-dir <path>", "Target directory for source").option("--id <id>", "Source id");
+    cli.command("remove <id...>", "Remove sources from the config and targets");
+    cli.command("sync", "Synchronize cache with config");
+    cli.command("status", "Show cache status");
+    cli.command("clean", "Remove project cache");
+    cli.command("clean-cache", "Clear global git cache");
+    cli.command("prune", "Remove unused data");
+    cli.command("verify", "Validate cache integrity");
+    cli.command("init", "Create a new config interactively");
+    const result = cli.parse(argv, { run: false });
+    const rawArgs = argv.slice(2);
+    const command = getCommandFromArgs(rawArgs);
+    const options = buildOptions(result);
+    assertAddOnlyOptions(command, rawArgs);
+    const { positionals, addEntries } = getPositionals(command, rawArgs, null);
+    const parsed = buildParsedCommand(
+      command,
+      options,
+      positionals,
+      addEntries
+    );
+    return {
+      command,
+      options,
+      positionals,
+      rawArgs,
+      help: Boolean(result.options.help),
+      parsed
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exit(ExitCode.InvalidArgument);
+  }
+};

package/dist/esm/cli/run.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/cli/run.mjs

@@ -0,0 +1,2 @@
+import { main } from "#cli/index";
+main();

package/dist/esm/cli/task-reporter.d.ts

@@ -0,0 +1,32 @@
+import { type LiveOutput } from "#cli/live-output";
+export type TaskReporterOptions = {
+    maxLiveLines?: number;
+    output?: LiveOutput;
+};
+export declare class TaskReporter {
+    private readonly output;
+    private readonly maxLiveLines;
+    private readonly startTime;
+    private readonly tasks;
+    private readonly results;
+    private readonly liveLines;
+    private readonly hasTty;
+    private timer;
+    private warnings;
+    private errors;
+    constructor(options?: TaskReporterOptions);
+    start(label: string): void;
+    info(label: string, details?: string): void;
+    warn(label: string, details?: string): void;
+    error(label: string, details?: string): void;
+    success(label: string, details?: string, icon?: string): void;
+    debug(text: string): void;
+    finish(summary?: string): void;
+    stop(): void;
+    private render;
+    private startTimer;
+    private stopTimer;
+    private composeView;
+    private hasRunningTasks;
+    private formatLine;
+}

package/dist/esm/cli/task-reporter.mjs

@@ -0,0 +1,122 @@
+import pc from "picocolors";
+import { createLiveOutput } from "#cli/live-output";
+import { symbols } from "#cli/ui";
+const formatDuration = (ms) => {
+  const seconds = Math.max(0, ms / 1e3);
+  if (seconds < 60) {
+    return `${seconds.toFixed(1)}s`;
+  }
+  const minutes = Math.floor(seconds / 60);
+  const remainder = seconds % 60;
+  return `${minutes}m ${remainder.toFixed(1)}s`;
+};
+export class TaskReporter {
+  output;
+  maxLiveLines;
+  startTime = Date.now();
+  tasks = /* @__PURE__ */ new Map();
+  results = [];
+  liveLines = [];
+  hasTty = Boolean(process.stdout.isTTY);
+  timer = null;
+  warnings = 0;
+  errors = 0;
+  constructor(options = {}) {
+    this.output = options.output ?? createLiveOutput();
+    this.maxLiveLines = options.maxLiveLines ?? 4;
+    this.startTimer();
+  }
+  start(label) {
+    this.tasks.set(label, "running");
+    this.render();
+  }
+  info(label, details) {
+    this.results.push(this.formatLine(symbols.info, label, details));
+    this.render();
+  }
+  warn(label, details) {
+    this.warnings += 1;
+    this.results.push(this.formatLine(symbols.warn, label, details));
+    this.render();
+  }
+  error(label, details) {
+    this.errors += 1;
+    this.results.push(this.formatLine(symbols.error, label, details));
+    this.render();
+  }
+  success(label, details, icon = symbols.success) {
+    this.tasks.set(label, "success");
+    this.results.push(this.formatLine(icon, label, details));
+    this.liveLines.length = 0;
+    this.render();
+  }
+  debug(text) {
+    this.liveLines.push(pc.dim(text));
+    if (this.liveLines.length > this.maxLiveLines) {
+      this.liveLines.splice(0, this.liveLines.length - this.maxLiveLines);
+    }
+    this.render();
+  }
+  finish(summary) {
+    this.liveLines.length = 0;
+    const durationMs = Date.now() - this.startTime;
+    const parts = [
+      `Completed in ${formatDuration(durationMs)}`,
+      this.warnings ? `${this.warnings} warning${this.warnings === 1 ? "" : "s"}` : null,
+      this.errors ? `${this.errors} error${this.errors === 1 ? "" : "s"}` : null
+    ].filter(Boolean);
+    const suffix = parts.length ? ` \xB7 ${parts.join(" \xB7 ")}` : "";
+    const message = summary ? `${summary}${suffix}` : `${symbols.info}${suffix}`;
+    this.output.persist(this.composeView([message]));
+    this.stopTimer();
+  }
+  stop() {
+    this.output.stop();
+    this.stopTimer();
+  }
+  render() {
+    if (!this.hasTty) return;
+    this.output.render(this.composeView());
+  }
+  startTimer() {
+    if (!this.hasTty) return;
+    this.timer = setInterval(() => {
+      if (this.hasRunningTasks()) {
+        this.render();
+      }
+    }, 100);
+    this.timer.unref?.();
+  }
+  stopTimer() {
+    if (!this.timer) return;
+    clearInterval(this.timer);
+    this.timer = null;
+  }
+  composeView(extraFooter) {
+    const running = Array.from(this.tasks.entries()).filter(([, state]) => state === "running").map(([label]) => `${pc.cyan("\u2192")} ${label}`);
+    const runningCount = running.length;
+    const completedCount = this.results.length;
+    const elapsed = this.hasRunningTasks() ? pc.dim(
+      `elapsed: ${formatDuration(Date.now() - this.startTime)} \xB7 ${runningCount} running \xB7 ${completedCount} completed`
+    ) : "";
+    const lines = [
+      ...this.results,
+      ...running,
+      ...this.liveLines,
+      elapsed,
+      ...extraFooter ?? []
+    ].filter((line) => line.length > 0);
+    return lines.length > 0 ? lines : [" "];
+  }
+  hasRunningTasks() {
+    for (const state of this.tasks.values()) {
+      if (state === "running") return true;
+    }
+    return false;
+  }
+  formatLine(icon, label, details) {
+    const partLabel = pc.bold(label);
+    const partDetails = details ? pc.gray(details) : "";
+    return `  ${icon} ${partLabel} ${partDetails}`.trimEnd();
+  }
+}

package/dist/esm/cli/types.d.ts

@@ -0,0 +1,51 @@
+export type CliOptions = {
+    config?: string;
+    cacheDir?: string;
+    offline: boolean;
+    failOnMiss: boolean;
+    lockOnly: boolean;
+    prune: boolean;
+    concurrency?: number;
+    json: boolean;
+    timeoutMs?: number;
+    silent: boolean;
+    verbose: boolean;
+};
+export type AddEntry = {
+    id?: string;
+    repo: string;
+    targetDir?: string;
+};
+export type CliCommand = {
+    command: "add";
+    entries: AddEntry[];
+    options: CliOptions;
+} | {
+    command: "remove";
+    ids: string[];
+    options: CliOptions;
+} | {
+    command: "sync";
+    options: CliOptions;
+} | {
+    command: "status";
+    options: CliOptions;
+} | {
+    command: "clean";
+    options: CliOptions;
+} | {
+    command: "clean-cache";
+    options: CliOptions;
+} | {
+    command: "prune";
+    options: CliOptions;
+} | {
+    command: "verify";
+    options: CliOptions;
+} | {
+    command: "init";
+    options: CliOptions;
+} | {
+    command: null;
+    options: CliOptions;
+};

package/dist/esm/cli/ui.d.ts

@@ -0,0 +1,21 @@
+export declare const symbols: {
+    error: any;
+    success: any;
+    synced: any;
+    info: any;
+    warn: any;
+};
+export declare const setSilentMode: (silent: boolean) => void;
+export declare const setVerboseMode: (verbose: boolean) => void;
+export declare const isSilentMode: () => boolean;
+export declare const isVerboseMode: () => boolean;
+export declare const ui: {
+    path: (value: string) => any;
+    hash: (value: string | null | undefined) => string;
+    pad: (value: string, length: number) => string;
+    line: (text?: string) => void;
+    header: (label: string, value: string) => void;
+    item: (icon: string, label: string, details?: string) => void;
+    step: (action: string, subject: string, details?: string) => void;
+    debug: (text: string) => void;
+};

package/dist/esm/cli/ui.mjs

@@ -0,0 +1,64 @@
+import path from "node:path";
+import pc from "picocolors";
+import { toPosixPath } from "#core/paths";
+export const symbols = {
+  error: pc.red("\u2716"),
+  success: pc.green("\u2714"),
+  synced: pc.green("\u25CF"),
+  info: pc.blue("\u2139"),
+  warn: pc.yellow("\u26A0")
+};
+let _silentMode = false;
+let _verboseMode = false;
+export const setSilentMode = (silent) => {
+  _silentMode = silent;
+};
+export const setVerboseMode = (verbose) => {
+  _verboseMode = verbose;
+};
+export const isSilentMode = () => _silentMode;
+export const isVerboseMode = () => _verboseMode;
+export const ui = {
+  // Formatters
+  path: (value) => {
+    const rel = path.relative(process.cwd(), value);
+    const selected = rel.length < value.length ? rel : value;
+    return toPosixPath(selected);
+  },
+  hash: (value) => {
+    return value ? value.slice(0, 7) : "-";
+  },
+  // Layout
+  pad: (value, length) => value.padEnd(length),
+  // Components
+  line: (text = "") => {
+    if (_silentMode) return;
+    process.stdout.write(`${text}
+`);
+  },
+  header: (label, value) => {
+    if (_silentMode) return;
+    process.stdout.write(`${pc.blue("\u2139")} ${label.padEnd(10)} ${value}
+`);
+  },
+  item: (icon, label, details) => {
+    if (_silentMode) return;
+    const partLabel = pc.bold(label);
+    const partDetails = details ? pc.gray(details) : "";
+    process.stdout.write(`  ${icon} ${partLabel} ${partDetails}
+`);
+  },
+  step: (action, subject, details) => {
+    if (_silentMode) return;
+    const icon = pc.cyan("\u2192");
+    process.stdout.write(
+      `  ${icon} ${action} ${pc.bold(subject)}${details ? ` ${pc.dim(details)}` : ""}
+`
+    );
+  },
+  debug: (text) => {
+    if (_silentMode || !_verboseMode) return;
+    process.stdout.write(`${pc.dim("\u2022")} ${pc.dim(text)}
+`);
+  }
+};

package/dist/esm/commands/add.d.ts

@@ -0,0 +1,20 @@
+export declare const addSources: (params: {
+    configPath?: string;
+    entries: Array<{
+        id?: string;
+        repo: string;
+        targetDir?: string;
+    }>;
+}) => Promise<{
+    configPath: any;
+    sources: {
+        id: string;
+        repo: string;
+        targetDir?: string;
+        ref?: string;
+    }[];
+    skipped: string[];
+    created: boolean;
+    gitignoreUpdated: any;
+    gitignorePath: any;
+}>;

package/dist/esm/commands/add.mjs

@@ -0,0 +1,81 @@
+import path from "node:path";
+import { DEFAULT_CACHE_DIR } from "#config";
+import {
+  mergeConfigBase,
+  readConfigAtPath,
+  resolveConfigTarget,
+  writeConfigFile
+} from "#config/io";
+import { ensureGitignoreEntry } from "#core/gitignore";
+import { resolveTargetDir } from "#core/paths";
+import { assertSafeSourceId } from "#core/source-id";
+import { resolveRepoInput } from "#git/resolve-repo";
+const buildNewSources = (entries, config, resolvedPath) => {
+  const existingIds = new Set(config.sources.map((source) => source.id));
+  const skipped = [];
+  const newSources = entries.map((entry) => {
+    const resolved = resolveRepoInput(entry.repo);
+    const sourceId = entry.id || resolved.inferredId;
+    if (!sourceId) {
+      throw new Error("Unable to infer id. Provide an explicit id.");
+    }
+    const safeId = assertSafeSourceId(sourceId, "source id");
+    if (existingIds.has(safeId)) {
+      skipped.push(safeId);
+      return null;
+    }
+    existingIds.add(safeId);
+    if (entry.targetDir) {
+      resolveTargetDir(resolvedPath, entry.targetDir);
+    }
+    return {
+      id: safeId,
+      repo: resolved.repoUrl,
+      ...entry.targetDir ? { targetDir: entry.targetDir } : {},
+      ...resolved.ref ? { ref: resolved.ref } : {}
+    };
+  }).filter(Boolean);
+  return { newSources, skipped };
+};
+const ensureGitignore = async (resolvedPath, cacheDir, shouldWrite) => {
+  if (!shouldWrite) {
+    return null;
+  }
+  return ensureGitignoreEntry(path.dirname(resolvedPath), cacheDir);
+};
+export const addSources = async (params) => {
+  const target = await resolveConfigTarget(params.configPath);
+  const resolvedPath = target.resolvedPath;
+  const { config, rawConfig, rawPackage, hadDocsCacheConfig } = await readConfigAtPath(target, { allowMissing: true });
+  const { newSources, skipped } = buildNewSources(
+    params.entries,
+    config,
+    resolvedPath
+  );
+  if (newSources.length === 0) {
+    throw new Error("All sources already exist in config.");
+  }
+  const nextConfig = mergeConfigBase(rawConfig ?? config, [
+    ...config.sources,
+    ...newSources
+  ]);
+  await writeConfigFile({
+    mode: target.mode,
+    resolvedPath,
+    config: nextConfig,
+    rawPackage
+  });
+  const gitignoreResult = await ensureGitignore(
+    resolvedPath,
+    rawConfig?.cacheDir ?? DEFAULT_CACHE_DIR,
+    !hadDocsCacheConfig
+  );
+  return {
+    configPath: resolvedPath,
+    sources: newSources,
+    skipped,
+    created: true,
+    gitignoreUpdated: gitignoreResult?.updated ?? false,
+    gitignorePath: gitignoreResult?.gitignorePath ?? null
+  };
+};