@opum-ai/lore 0.1.0 → 0.2.0

package/src/commands/graph.ts

@@ -1,291 +0,0 @@
-/**
- * commands/graph.ts — `lore graph [<id>] [--dot] [--depth <n>]`.
- *
- * The thin, read-only layer that emits the bundle's cross-link graph (cli-surface
- * §graph; LORE-31). Commander supplies a verified indexed {@link BundleGraph}
- * with automatic reference fallback; direct core callers retain the reference
- * loader. The selected graph is then shaped as follows:
- *
- * - with **no `<id>`** exports the whole bundle;
- * - with an `<id>` exports the **subgraph** rooted there, bounded to `--depth`
- *   hops ({@link subgraph}; unbounded when `--depth` is omitted).
- *
- * Output follows the uniform CLI modes: a human node/edge listing at a TTY (or
- * piped plain), and the `{schemaVersion, kind: "graph.export", data}` envelope
- * under the global `--json` — there is no command-specific JSON flag, so machine
- * consumers use the same `--json` they use everywhere. `--dot` is the one
- * representation override: it emits Graphviz DOT instead of the listing, so `lore
- * graph --dot | dot -Tpng` works (a piped stdout auto-selects plain). `--dot` and
- * `--json` are mutually exclusive — DOT has no envelope form.
- *
- * The positional `<id>` is normalized through {@link idFromPath} exactly as `lore
- * rename`/`supersede` normalize theirs, so a path-form, `./`-prefixed, or
- * `.md`-suffixed id resolves to the same bundle key (consistent id acceptance
- * across the id-taking commands).
- *
- * Validation lives here (the byte/shape computation stays pure in `core/graph.ts`
- * and `core/query.ts`): an unknown flag, a repeated/value-less or value-bearing
- * `--dot`, a repeated/value-less/non-integer/too-large `--depth`, a `--depth`
- * without a root `<id>`, `--dot` together with `--json`, or a stray second
- * positional is a `usage` error (exit 2); a root `<id>` absent from the bundle
- * surfaces as the `not_found` error (exit 3) {@link subgraph} throws.
- */
-
-import { join } from "node:path";
-import type { BacklogAdapter } from "../adapters/backlog";
-import { loadBundle } from "../core/bundle";
-import { idFromPath } from "../core/concept";
-import { buildGraphExport, type GraphExport, toDot } from "../core/graph";
-import { loadProfile } from "../core/profile";
-import { subgraph } from "../core/query";
-import { loadRetrievalGraph, type RetrievalGraphLoader } from "../core/retrieval";
-import { DOCS_DIR } from "../core/scaffold";
-import { parseQualifiedWorkspaceId, qualifyWorkspaceId } from "../core/workspace-contract";
-import type { WorkspaceRetrievalContext, WorkspaceRetrievalSelection } from "../core/workspace-retrieval";
-import { EXIT_OK, LoreError, singleLine, WarningCollector, type Writer } from "../errors";
-import { emit, type OutputContext, type Renderable } from "../output";
-import { assertFlagAtMostOnce, parseCommandArgs, singleOptionValue, workspaceSelection } from "./args";
-
-/** Options for {@link runGraph}; `root` and the streams are injectable for tests. */
-export interface GraphOptions {
-  /** The repo root the `docs/` bundle resolves against. */
-  root: string;
-  /** The resolved output mode/color (from `output.ts`). */
-  output: OutputContext;
-  /** The command's normalized positional + flag tokens from Commander. */
-  args: readonly string[];
-  /** stdout sink; defaults to `process.stdout`. */
-  stdout?: Writer;
-  /** stderr sink for advisory warnings; defaults to `process.stderr`. */
-  stderr?: Writer;
-  /** Backlog snapshot seam used only by indexed projection freshness/builds. */
-  adapter?: BacklogAdapter;
-  /** Indexed/reference selector injected by the Commander handler or conformance tests. */
-  retrieval?: RetrievalGraphLoader;
-}
-
-/** The parsed form of `lore graph`'s arguments. */
-interface GraphArgs {
-  /** The root concept id (positional, already {@link idFromPath}-normalized); `undefined` exports the whole bundle. */
-  id?: string;
-  /** Emit Graphviz DOT instead of the node/edge listing (`--dot`). */
-  dot: boolean;
-  /** The hop radius (`--depth`); `undefined` means unbounded. Requires `id`. */
-  depth?: number;
-  readonly workspace?: WorkspaceRetrievalSelection;
-}
-
-/**
- * Run `lore graph`: parse the arguments, load the bundle, narrow to the rooted
- * subgraph when an `<id>` is given, shape the export, emit the `graph.export`,
- * and return `0`. A bad flag/positional (including `--dot` with `--json`) throws
- * a `usage` {@link LoreError} (exit `2`); an `<id>` not in the bundle a
- * `not_found` one (exit `3`).
- */
-export function runGraph(options: GraphOptions): number | Promise<number> {
-  const parsed = parseGraphArgs(options.args);
-  if (parsed.dot && options.output.mode === "json") {
-    throw usage("--dot cannot be combined with --json", "DOT has no JSON envelope; pass one of --dot or --json");
-  }
-  const advisories = new WarningCollector();
-  const retrieval = options.retrieval ?? (parsed.workspace !== undefined ? loadRetrievalGraph : undefined);
-  if (retrieval !== undefined) {
-    return retrieval({
-      root: options.root,
-      warnings: advisories,
-      adapter: options.adapter,
-      ...(parsed.workspace !== undefined ? { workspace: parsed.workspace } : {}),
-    }).then(async (loaded) => {
-      try {
-        return finishGraph(options, parsed, loaded.graph, advisories, loaded.workspace);
-      } finally {
-        await loaded.dispose?.();
-      }
-    });
-  }
-  const profile = loadProfile({ root: options.root });
-  const graph = loadBundle(join(options.root, DOCS_DIR), { warnings: advisories, profile });
-  return finishGraph(options, parsed, graph, advisories);
-}
-
-function finishGraph(
-  options: GraphOptions,
-  parsed: GraphArgs,
-  graph: ReturnType<typeof loadBundle>,
-  advisories: WarningCollector,
-  workspace?: WorkspaceRetrievalContext,
-): number {
-  // Flush load warnings before the subgraph lookup, which throws not_found for an
-  // unknown root — otherwise an advisory that explains *why* a file is not a
-  // concept would be discarded on exactly the path that most needs it.
-  advisories.flush({ color: options.output.color, stderr: options.stderr });
-
-  let data: GraphExport;
-  if (parsed.id === undefined) {
-    data = buildGraphExport(graph, workspaceOptions(workspace));
-  } else {
-    const include = subgraph(graph, parsed.id, parsed.depth ?? Number.POSITIVE_INFINITY);
-    data = buildGraphExport(graph, {
-      include,
-      root: parsed.id,
-      depth: parsed.depth,
-      ...workspaceOptions(workspace, include),
-    });
-  }
-
-  emit(graphRenderable(data, parsed.dot), options.output, options.stdout);
-  return EXIT_OK;
-}
-
-// ── Argument parsing ───────────────────────────────────────────────────────────
-
-/**
- * Parse `graph`'s tokens into the optional root `<id>` positional, the boolean
- * `--dot`, and the value flag `--depth <n>` (also accepting `--depth=<n>`). The
- * Commander has already resolved Lore's global flags, so a `--`-prefixed token here
- * is a command flag: an unrecognized one is a `usage` error, as is a repeated or
- * value-bearing `--dot`, a repeated/value-less/non-integer/too-large `--depth`, a
- * `--depth` with no root, or a second positional. A `--` ends option parsing. The
- * `<id>` is {@link idFromPath}-normalized so path/`.md`/`./` forms resolve.
- */
-function parseGraphArgs(args: readonly string[]): GraphArgs {
-  const parsed = parseCommandArgs(args, "graph");
-  const workspace = workspaceSelection(parsed);
-  const positionals = parsed.positionals;
-  assertFlagAtMostOnce(parsed, "dot");
-  const rawDepth = singleOptionValue(parsed, "depth");
-  if (rawDepth === "") throw usage("--depth needs a value", "pass a value, e.g. `--depth 2`");
-  const depth = rawDepth === undefined ? undefined : parseDepth(rawDepth);
-  if (positionals.length > 1) {
-    throw usage(`unexpected argument "${positionals[1]}"`, "run `lore graph [<id>] [--dot] [--depth <n>]`");
-  }
-  const raw = positionals[0];
-  if (depth !== undefined && raw === undefined) {
-    throw usage(
-      "--depth needs a root <id>",
-      "give the concept to bound the radius from, e.g. `lore graph <id> --depth 2`",
-    );
-  }
-  return {
-    id: raw !== undefined ? normalizeGraphId(raw, workspace !== undefined) : undefined,
-    dot: parsed.flags.has("dot"),
-    depth,
-    workspace,
-  };
-}
-
-function normalizeGraphId(raw: string, workspace: boolean): string {
-  if (!workspace) return idFromPath(raw);
-  try {
-    const parsed = parseQualifiedWorkspaceId(raw);
-    return qualifyWorkspaceId(parsed.memberId, idFromPath(parsed.sourceId));
-  } catch {
-    throw usage(`invalid workspace concept id "${raw}"`, "use the unambiguous <member-id>::<source-id> form");
-  }
-}
-
-function workspaceOptions(workspace?: WorkspaceRetrievalContext, include?: ReadonlySet<string>) {
-  if (workspace === undefined) return {};
-  const links =
-    include === undefined
-      ? workspace.links
-      : workspace.links.filter(
-          (link) =>
-            include.has(qualifyWorkspaceId(link.from.memberId, link.from.sourceId)) &&
-            include.has(qualifyWorkspaceId(link.to.memberId, link.to.sourceId)),
-        );
-  return {
-    workspace: workspace.scope,
-    provenanceById: workspace.provenanceById,
-    workspaceLinks: links,
-  };
-}
-
-/** Parse a `--depth` value as a non-negative, safe integer (`0` = root only). */
-function parseDepth(value: string): number {
-  // Accept only a bare run of digits — Number() would coerce "1.5"/"0x2"/" 2 "/"1e3".
-  if (!/^\d+$/.test(value)) {
-    throw usage(
-      `invalid --depth "${value}"`,
-      "pass a non-negative integer, e.g. `--depth 2`; --depth needs a value before a separate flag-looking token",
-    );
-  }
-  const depth = Number.parseInt(value, 10);
-  // A >2^53 run of digits parses without error but loses precision, so the echoed
-  // `depth` would differ from what the user typed; reject it rather than lie.
-  if (!Number.isSafeInteger(depth)) {
-    throw usage(`--depth "${value}" is too large`, "pass a smaller non-negative integer");
-  }
-  return depth;
-}
-
-/**
- * Read a value flag's argument: its inline `--flag=value` form when present, else
- * the **next** token. A missing/empty value — or a next token that is itself an
- * option (`--depth --dot`) — is a `usage` error rather than a silently swallowed
- * flag (mirroring `lore schema`'s value-flag guard).
- */
-// ── Output ─────────────────────────────────────────────────────────────────────
-
-/**
- * The per-result rendering bundle for `graph` (output.ts dispatches on the mode).
- * `--json` always carries the structured {@link GraphExport}; the pretty/plain
- * text is the DOT serialization under `--dot`, else a human node/edge listing.
- * The two text modes render identically (the data is structural — no severities
- * to color), so pretty and plain share one renderer.
- */
-function graphRenderable(data: GraphExport, dot: boolean): Renderable<GraphExport> {
-  const render = dot ? toDot : renderText;
-  return { kind: "graph.export", data, pretty: render, plain: render };
-}
-
-/**
- * A human/pipe-stable listing: a `<n> concepts, <m> edges, ~<t> tokens` header
- * (annotating the scope when it is a subgraph), one `<id>  [type]  ~<tok>` line
- * per node, then one `<from> -<kind>-> <to>` line per edge (`(dangling: <target>)`
- * for a broken reference). ANSI-free and deterministic.
- *
- * `node.id`/`node.type`/`node.title`/edge endpoints all come from bundle-controlled
- * frontmatter (an edge's `from`/`to` are concept ids; `target` is the reference
- * as parsed, which for a dangling `specs`/frontmatter edge can carry whatever a
- * YAML scalar allows — including an embedded newline; `node.type` mirrors
- * `frontmatter.type`, and `requireType` (schema.ts) only trims the *ends* of the
- * value while unknown types are warn-only, so an interior newline in `type:`
- * survives bundle load unchanged), so each is run through {@link singleLine}
- * before it lands in a line — the same guard every other bundle-text renderer
- * applies (managed-block.ts, indexes.ts, context.ts, query.ts, log.ts) — so an
- * embedded newline/control character cannot split one node or edge into extra
- * physical lines. `data.root` is included for the same reason: though only
- * reachable via a concept id that itself embeds a newline, guarding it keeps
- * the header consistent with every id printed below it.
- */
-function renderText(data: GraphExport): string {
-  const root = data.root !== undefined ? singleLine(data.root) : undefined;
-  const scope =
-    root !== undefined ? ` rooted at ${root}${data.depth !== undefined ? ` (depth ${data.depth})` : ""}` : "";
-  const lines = [
-    ...(data.workspace !== undefined
-      ? [`workspace: ${singleLine(data.workspace.workspaceId)} (${data.workspace.repositories.length} repositories)`]
-      : []),
-    `${data.nodes.length} ${plural(data.nodes.length, "concept")}, ${data.edges.length} ${plural(data.edges.length, "edge")}, ~${data.tokenEstimate} tokens (chars/4)${scope}`,
-  ];
-  for (const node of data.nodes) {
-    const title = node.title !== undefined ? `  ${singleLine(node.title)}` : "";
-    lines.push(`  ${singleLine(node.id)}  [${singleLine(node.type)}]  ~${node.tokenEstimate}${title}`);
-  }
-  for (const edge of data.edges) {
-    const dest = edge.to !== null ? singleLine(edge.to) : `(dangling: ${singleLine(edge.target)})`;
-    lines.push(`  ${singleLine(edge.from)} -${edge.kind}-> ${dest}`);
-  }
-  return lines.join("\n");
-}
-
-/** Pluralize a noun by count (`1 concept` / `2 concepts`). */
-function plural(count: number, noun: string): string {
-  return count === 1 ? noun : `${noun}s`;
-}
-
-/** A `usage` {@link LoreError} (exit `2`) with an actionable hint. */
-function usage(message: string, hint: string): LoreError {
-  return new LoreError("usage", message, hint);
-}

package/src/commands/help.ts

@@ -1,151 +0,0 @@
-/**
- * commands/help.ts — `lore help [<command>]` (cli-surface §help).
- *
- * The thin, read-only layer over the capability manifest in `core/manifest.ts`:
- * it parses the one optional `<command>` positional and emits either the whole
- * manifest or one command's entry. Like `instructions`, there is no bundle to
- * load and no config to read, so it needs neither `root` nor a `WarningCollector`.
- *
- * - `lore help` — top-level help (the command catalog), rendered from the manifest.
- * - `lore help <command>` — one command's detailed help; an unknown `<command>`
- *   is a `not_found` error (exit 3) whose hint lists the valid names.
- * - `--json` — the `{schemaVersion, kind: "help.manifest", data}` envelope, where
- *   `data` is the full {@link Manifest} (or, for `lore help <command> --json`, the
- *   same {@link Manifest} shape scoped to the one requested command, so a consumer
- *   parses both forms identically).
- *
- * {@link renderTopLevelHelp} is exported so the router's `--help`/no-command
- * short-circuit renders from the same manifest — one source for all help text, no
- * separately-maintained `USAGE` literal to drift.
- */
-
-import {
-  buildManifest,
-  findManifestCommand,
-  type Manifest,
-  type ManifestCommand,
-  type ManifestFlag,
-} from "../core/manifest";
-import { EXIT_OK, LoreError, type Writer } from "../errors";
-import { VERSION } from "../meta";
-import { emit, type OutputContext, type Renderable } from "../output";
-import { parseCommandArgs, usage } from "./args";
-
-/** Options for {@link runHelp}; the stream is injectable for tests. */
-export interface HelpOptions {
-  /** The resolved output mode/color (from `output.ts`). */
-  output: OutputContext;
-  /** The command's normalized positional tokens from Commander. */
-  args: readonly string[];
-  /** stdout sink; defaults to `process.stdout`. */
-  stdout?: Writer;
-}
-
-/** Run `lore help`: parse the optional `<command>`, resolve it, emit its (or the whole) manifest, and return `0`. */
-export function runHelp(options: HelpOptions): number {
-  const name = parseHelpArgs(options.args);
-  const manifest = buildManifest();
-  if (name !== undefined) {
-    const command = findManifestCommand(name);
-    if (command === undefined) {
-      const validNames = manifest.commands.map((c) => c.name).join(", ");
-      throw new LoreError(
-        "not_found",
-        `unknown command "${name}"`,
-        `valid commands: ${validNames}; run \`lore help\` to list them`,
-        { command: name },
-      );
-    }
-    emit(commandHelpRenderable(manifest, command), options.output, options.stdout);
-    return EXIT_OK;
-  }
-  emit(topLevelHelpRenderable(manifest), options.output, options.stdout);
-  return EXIT_OK;
-}
-
-/** Parse `help`'s tokens via the shared parser (no known flags): at most one positional (the command name); a flag or second positional is a `usage` error. */
-function parseHelpArgs(args: readonly string[]): string | undefined {
-  const { positionals } = parseCommandArgs(args, "help");
-  if (positionals.length > 1) {
-    throw usage(`unexpected argument "${positionals[1]}"`, "run `lore help [<command>]`");
-  }
-  return positionals[0];
-}
-
-/** The whole-manifest {@link Renderable}: `data` is the full manifest; pretty/plain are the top-level command catalog. */
-function topLevelHelpRenderable(manifest: Manifest): Renderable<Manifest> {
-  const text = renderTopLevelHelp(manifest);
-  return { kind: "help.manifest", data: manifest, pretty: () => text, plain: () => text };
-}
-
-/** One command's {@link Renderable}: `data` is the manifest scoped to that command (same shape as the full one); pretty/plain are its detailed help. */
-function commandHelpRenderable(manifest: Manifest, command: ManifestCommand): Renderable<Manifest> {
-  const text = renderCommandHelp(command);
-  const data: Manifest = { ...manifest, commands: [command] };
-  return { kind: "help.manifest", data, pretty: () => text, plain: () => text };
-}
-
-/**
- * Render the top-level help — the header, the command catalog, and the global
- * options — from the manifest. Uncolored, so the `lore help` command and the
- * `lore --help` flag (which the router feeds this same text) are byte-identical.
- * Exported for the router's `--help`/no-command short-circuit.
- */
-export function renderTopLevelHelp(manifest: Manifest = buildManifest()): string {
-  const nameWidth = Math.max(...manifest.commands.map((c) => c.name.length));
-  const commands = manifest.commands
-    .map((c) => `  ${c.name.padEnd(nameWidth)}  ${c.summary}${c.args ? ` (lore ${c.name} ${c.args})` : ""}`)
-    .join("\n");
-  const optWidth = Math.max(...manifest.globalFlags.map((f) => globalFlagLabel(f).length));
-  const options = manifest.globalFlags.map((f) => `  ${globalFlagLabel(f).padEnd(optWidth)}  ${f.summary}`).join("\n");
-  return `lore ${VERSION} — OKF-native documentation CLI
-
-Usage:
-  lore <command> [options]
-
-Commands:
-${commands}
-
-Run \`lore help <command>\` for a command's arguments, flags, output, and exit codes.
-
-Options:
-${options}
-
-Docs: docs/index.md`;
-}
-
-/** Render one command's detailed help: usage line, flags, output kind, exit codes, and examples. */
-function renderCommandHelp(command: ManifestCommand): string {
-  const lines: string[] = [
-    `lore ${command.name} — ${command.summary}`,
-    "",
-    "Usage:",
-    `  lore ${command.name}${command.args ? ` ${command.args}` : ""}`,
-  ];
-  if (command.flags.length > 0) {
-    const width = Math.max(...command.flags.map((f) => commandFlagLabel(f).length));
-    lines.push("", "Flags:");
-    for (const flag of command.flags) {
-      const note = flag.repeatable ? " (repeatable)" : "";
-      lines.push(`  ${commandFlagLabel(flag).padEnd(width)}  ${flag.summary}${note}`);
-    }
-  }
-  lines.push("", `Output:  ${command.kind} (--json envelope)`, `Exit codes:  ${command.exitCodes.join(", ")}`);
-  if (command.examples.length > 0) {
-    lines.push("", "Examples:");
-    for (const example of command.examples) {
-      lines.push(`  ${example}`);
-    }
-  }
-  return lines.join("\n");
-}
-
-/** `-v, --version` when a flag has a short alias, else `--json`. */
-function globalFlagLabel(flag: ManifestFlag): string {
-  return flag.alias !== undefined ? `-${flag.alias}, --${flag.name}` : `--${flag.name}`;
-}
-
-/** `--type <value>` for a value-taking flag, else `--strict`. */
-function commandFlagLabel(flag: ManifestFlag): string {
-  return flag.takesValue ? `--${flag.name} <value>` : `--${flag.name}`;
-}

package/src/commands/impact.ts

@@ -1,59 +0,0 @@
-/** `lore impact`: bounded deterministic impact expansion across exact authored typed edges. */
-
-import type { BacklogAdapter } from "../adapters/backlog";
-import { loadRetrievalGraph, type RetrievalGraphLoader } from "../core/retrieval";
-import { findImpact } from "../core/traversal";
-import { EXIT_OK, LoreError, WarningCollector, type Writer } from "../errors";
-import { emit, type OutputContext } from "../output";
-import { parseCommandArgs, usage, workspaceSelection } from "./args";
-import {
-  assertKnownEdgeKinds,
-  impactRenderable,
-  normalizeEndpointId,
-  parseEndpointKind,
-  parseTraversalFlags,
-} from "./traversal";
-
-export interface ImpactCommandOptions {
-  readonly root: string;
-  readonly output: OutputContext;
-  readonly args: readonly string[];
-  readonly stdout?: Writer;
-  readonly stderr?: Writer;
-  readonly adapter?: BacklogAdapter;
-  readonly retrieval?: RetrievalGraphLoader;
-}
-
-export async function runImpact(options: ImpactCommandOptions): Promise<number> {
-  const parsed = parseCommandArgs(options.args, "impact");
-  const workspace = workspaceSelection(parsed);
-  if (parsed.positionals.length !== 1) {
-    throw usage("impact needs exactly one <id>", "run `lore impact <id> --kind <kind> --direction <direction>`");
-  }
-  const kind = parseEndpointKind(parsed, "kind");
-  const flags = parseTraversalFlags(parsed);
-  const advisories = new WarningCollector();
-  const loaded = await (options.retrieval ?? loadRetrievalGraph)({
-    root: options.root,
-    warnings: advisories,
-    adapter: options.adapter,
-    includeTraversal: true,
-    ...(workspace !== undefined ? { workspace } : {}),
-  });
-  try {
-    advisories.flush({ color: options.output.color, stderr: options.stderr });
-    if (loaded.traversal === undefined) throw new LoreError("validation", "traversal snapshot was not loaded");
-    assertKnownEdgeKinds(loaded.traversal, flags.edgeKinds);
-    const data = findImpact(loaded.traversal, {
-      root: {
-        kind,
-        id: normalizeEndpointId(parsed.positionals[0] as string, kind, workspace !== undefined),
-      },
-      ...flags,
-    });
-    emit(impactRenderable(data), options.output, options.stdout);
-    return EXIT_OK;
-  } finally {
-    await loaded.dispose?.();
-  }
-}