@opum-ai/lore 0.1.0

package/src/commands/explorer.ts

@@ -0,0 +1,253 @@
+/** `lore explorer [--out <file>] [--force]` — deterministic offline graph artifact generation. */
+
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import type { BacklogAdapter } from "../adapters/backlog";
+import {
+  buildExplorerChangeSnapshot,
+  buildExplorerSnapshot,
+  EXPLORER_ARTIFACT_VERSION,
+  explorerArtifactDigest,
+  renderExplorerArtifact,
+  renderExplorerChangeArtifact,
+} from "../core/explorer";
+import type { ExplorerSnapshot } from "../core/explorer-contract";
+import { EXPECTED_LADYBUG_STORAGE_VERSION, EXPECTED_LADYBUG_VERSION } from "../core/ladybug-native";
+import { loadLadybugProjectionSource } from "../core/ladybug-source";
+import type { RetainedSnapshot } from "../core/snapshot";
+import { resolveSnapshotScope } from "../core/snapshot-runtime";
+import { loadSnapshot as loadStoredSnapshot } from "../core/snapshot-store";
+import { EXIT_OK, LoreError, WarningCollector, type Writer } from "../errors";
+import { emit, type OutputContext, type Renderable } from "../output";
+import { assertFlagAtMostOnce, parseCommandArgs, singleOptionValue, usage, workspaceSelection } from "./args";
+import { assertNoSymlinkInPath, classifyExistingFile, ensureDir, writeFileAtomic } from "./fswrite";
+
+export const DEFAULT_EXPLORER_ARTIFACT_PATH = ".lore/explorer/index.html";
+
+export interface ExplorerCommandOptions {
+  readonly root: string;
+  readonly output: OutputContext;
+  readonly args: readonly string[];
+  readonly stdout?: Writer;
+  readonly stderr?: Writer;
+  readonly adapter?: BacklogAdapter;
+  readonly loadSnapshot?: ExplorerSnapshotLoader;
+  readonly loadRetainedSnapshot?: (selector: string) => RetainedSnapshot | Promise<RetainedSnapshot>;
+}
+
+export interface ExplorerSnapshotLoaderOptions {
+  readonly root: string;
+  readonly adapter?: BacklogAdapter;
+  readonly warnings: WarningCollector;
+}
+
+export type ExplorerSnapshotLoader = (options: ExplorerSnapshotLoaderOptions) => Promise<ExplorerSnapshot>;
+
+export interface ExplorerArtifactResult {
+  readonly artifactVersion: typeof EXPLORER_ARTIFACT_VERSION;
+  readonly snapshotSchemaVersion: string;
+  readonly snapshotKey: string;
+  readonly path: string;
+  readonly action: "created" | "updated" | "unchanged";
+  readonly byteLength: number;
+  readonly digest: string;
+  readonly counts: ExplorerSnapshot["health"]["counts"];
+}
+
+interface ExplorerArgs {
+  readonly out: string;
+  readonly customOut: boolean;
+  readonly force: boolean;
+  readonly snapshot?: string;
+  readonly from?: string;
+  readonly to?: string;
+  readonly workspace?: { readonly manifestPath: string; readonly memberIds: readonly string[] };
+}
+
+export async function runExplorer(options: ExplorerCommandOptions): Promise<number> {
+  const parsed = parseExplorerArgs(options.args);
+  const target = confineArtifactPath(parsed.out, options.root);
+  const warnings = new WarningCollector();
+  let html: string;
+  let schemaVersion: string;
+  let snapshotKey: string;
+  let counts: ExplorerSnapshot["health"]["counts"];
+  if (parsed.snapshot !== undefined || parsed.from !== undefined) {
+    let scope: Awaited<ReturnType<typeof resolveSnapshotScope>> | undefined;
+    const loadRetained = async (selector: string): Promise<RetainedSnapshot> => {
+      if (options.loadRetainedSnapshot !== undefined) return options.loadRetainedSnapshot(selector);
+      scope ??= await resolveSnapshotScope({
+        root: options.root,
+        selection: parsed.workspace === undefined ? {} : { workspace: parsed.workspace.manifestPath },
+        warnings,
+        adapter: options.adapter,
+      });
+      return loadStoredSnapshot(options.root, scope, selector);
+    };
+    const from = await loadRetained(parsed.snapshot ?? (parsed.from as string));
+    const to = parsed.snapshot !== undefined ? from : await loadRetained(parsed.to as string);
+    const retained = buildExplorerChangeSnapshot(from, to, {
+      mode: parsed.snapshot !== undefined ? "snapshot" : "comparison",
+      repositories: parsed.workspace?.memberIds ?? [],
+    });
+    html = renderExplorerChangeArtifact(retained);
+    schemaVersion = retained.schemaVersion;
+    snapshotKey = retained.to.snapshotKey;
+    counts = retainedCounts(retained.to, parsed.workspace?.memberIds ?? []);
+  } else {
+    const snapshot = await (options.loadSnapshot ?? loadProductionSnapshot)({
+      root: options.root,
+      adapter: options.adapter,
+      warnings,
+    });
+    html = renderExplorerArtifact(snapshot);
+    schemaVersion = snapshot.schemaVersion;
+    snapshotKey = snapshot.source.snapshotKey;
+    counts = snapshot.health.counts;
+  }
+  warnings.flush({ color: options.output.color, stderr: options.stderr });
+  assertNoSymlinkInPath(options.root, target.relPath);
+  const existing = classifyExistingFile(target.absPath, html);
+  if (parsed.customOut && existing === "differs" && !parsed.force) {
+    throw new LoreError(
+      "conflict",
+      `cannot overwrite differing explorer artifact ${target.relPath}`,
+      "pass --force to replace it, choose another --out path, or remove the existing file",
+      { path: target.relPath },
+    );
+  }
+  const action = existing === "missing" ? "created" : existing === "unchanged" ? "unchanged" : "updated";
+  if (action !== "unchanged") {
+    const parent = dirname(target.relPath);
+    if (parent !== ".") ensureDir(options.root, parent);
+    writeFileAtomic(target.absPath, html, target.relPath);
+  }
+  const data: ExplorerArtifactResult = {
+    artifactVersion: EXPLORER_ARTIFACT_VERSION,
+    snapshotSchemaVersion: schemaVersion,
+    snapshotKey,
+    path: target.relPath,
+    action,
+    byteLength: Buffer.byteLength(html),
+    digest: explorerArtifactDigest(html),
+    counts,
+  };
+  emit(explorerRenderable(data), options.output, options.stdout);
+  return EXIT_OK;
+}
+
+async function loadProductionSnapshot(options: ExplorerSnapshotLoaderOptions): Promise<ExplorerSnapshot> {
+  const source = await loadLadybugProjectionSource({
+    root: options.root,
+    ladybugVersion: EXPECTED_LADYBUG_VERSION,
+    ladybugStorageVersion: EXPECTED_LADYBUG_STORAGE_VERSION,
+    adapter: options.adapter,
+    warnings: options.warnings,
+  });
+  return buildExplorerSnapshot(source);
+}
+
+function parseExplorerArgs(args: readonly string[]): ExplorerArgs {
+  const parsed = parseCommandArgs(args, "explorer");
+  assertFlagAtMostOnce(parsed, "out");
+  assertFlagAtMostOnce(parsed, "force");
+  const workspace = workspaceSelection(parsed);
+  if (parsed.positionals.length > 0) {
+    throw usage(`unexpected argument "${parsed.positionals[0]}"`, "run `lore explorer [--out <file>] [--force]`");
+  }
+  const out = singleOptionValue(parsed, "out");
+  const snapshot = nonEmptySelector(singleOptionValue(parsed, "snapshot"), "snapshot");
+  const from = nonEmptySelector(singleOptionValue(parsed, "from"), "from");
+  const to = nonEmptySelector(singleOptionValue(parsed, "to"), "to");
+  if (out === "") throw usage("--out needs a value", "pass a repository-relative .html file path");
+  if (snapshot !== undefined && (from !== undefined || to !== undefined)) {
+    throw usage(
+      "--snapshot is mutually exclusive with --from and --to",
+      "choose a retained snapshot view or a comparison",
+    );
+  }
+  if ((from === undefined) !== (to === undefined)) {
+    throw usage("--from and --to must be supplied together", "pass both retained snapshot selectors");
+  }
+  if (workspace !== undefined && snapshot === undefined && from === undefined) {
+    throw usage("--workspace requires retained snapshot selectors", "pass --snapshot or both --from and --to");
+  }
+  return {
+    out: out ?? DEFAULT_EXPLORER_ARTIFACT_PATH,
+    customOut: out !== undefined,
+    force: parsed.flags.has("force"),
+    ...(snapshot !== undefined ? { snapshot } : {}),
+    ...(from !== undefined ? { from, to: to as string } : {}),
+    ...(workspace !== undefined ? { workspace } : {}),
+  };
+}
+
+function nonEmptySelector(value: string | undefined, flag: string): string | undefined {
+  if (value === undefined) return undefined;
+  if (value.trim() === "")
+    throw usage(`--${flag} needs a value`, "pass an exact retained snapshot key or unambiguous commit");
+  return value.trim();
+}
+
+function retainedCounts(
+  snapshot: RetainedSnapshot,
+  repositories: readonly string[],
+): ExplorerSnapshot["health"]["counts"] {
+  const selected = new Set(repositories);
+  const facts = snapshot.facts.filter(
+    (fact) => selected.size === 0 || (fact.provenance.memberId !== null && selected.has(fact.provenance.memberId)),
+  );
+  const edgeFingerprints = new Set<string>();
+  let danglingEdges = 0;
+  let duplicateEdges = 0;
+  for (const fact of facts) {
+    if (fact.kind !== "edge") continue;
+    if (fact.value.dangling === true) danglingEdges += 1;
+    const fingerprint = [fact.value.from, fact.value.kind, fact.value.target].join("\0");
+    if (edgeFingerprints.has(fingerprint)) duplicateEdges += 1;
+    edgeFingerprints.add(fingerprint);
+  }
+  return {
+    repositories:
+      selected.size === 0
+        ? snapshot.repositories.length
+        : snapshot.repositories.filter(
+            (repository) => repository.memberId !== null && selected.has(repository.memberId),
+          ).length,
+    concepts: facts.filter((fact) => fact.kind === "concept").length,
+    tasks: facts.filter((fact) => fact.kind === "task").length,
+    authoredEdges: facts.filter((fact) => fact.kind === "edge").length,
+    danglingEdges,
+    duplicateEdges,
+  };
+}
+
+function confineArtifactPath(path: string, root: string): { readonly absPath: string; readonly relPath: string } {
+  const absPath = resolve(root, path);
+  const rel = relative(root, absPath);
+  if (isAbsolute(path) || rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    throw usage(`--out path "${path}" must name a file inside the repo`, "give --out a repo-relative .html file path");
+  }
+  const relPath = rel.split(sep).join("/");
+  const first = relPath.split("/")[0]?.toLowerCase();
+  if (first === "docs" || first === "backlog" || first === ".git") {
+    throw usage(
+      `--out path "${path}" targets protected repository source`,
+      "write the derived artifact outside docs/, backlog/, and .git/, e.g. .lore/explorer/index.html",
+    );
+  }
+  if (!relPath.toLowerCase().endsWith(".html")) {
+    throw usage(`--out path "${path}" must end in .html`, "pass a self-contained HTML artifact path");
+  }
+  return { absPath, relPath };
+}
+
+function explorerRenderable(data: ExplorerArtifactResult): Renderable<ExplorerArtifactResult> {
+  return { kind: "explorer.artifact", data, pretty: renderText, plain: renderText };
+}
+
+function renderText(data: ExplorerArtifactResult): string {
+  return [
+    `${data.action} ${data.path} (${data.byteLength} bytes, ${data.artifactVersion})`,
+    `snapshot ${data.snapshotKey}: ${data.counts.concepts} concepts, ${data.counts.tasks} tasks, ${data.counts.authoredEdges} edges`,
+  ].join("\n");
+}

package/src/commands/export.ts

@@ -0,0 +1,93 @@
+/** `lore export --schema-version 1.0` — deterministic JSONL OKF projection. */
+
+import { join } from "node:path";
+import { type BacklogAdapter, bunBacklogSpawn, createBacklogAdapter } from "../adapters/backlog";
+import { resolveHeadSha } from "../adapters/git";
+import { loadBundle } from "../core/bundle";
+import { loadProfile } from "../core/profile";
+import { buildProjection, PROJECTION_SCHEMA_VERSION } from "../core/projection";
+import { DOCS_DIR } from "../core/scaffold";
+import { EXIT_OK, LoreError, WarningCollector, type Writer } from "../errors";
+import { VERSION } from "../meta";
+import { emit, type OutputContext, type Renderable } from "../output";
+import { parseCommandArgs, singleOptionValue } from "./args";
+
+export interface ExportOptions {
+  readonly root: string;
+  readonly output: OutputContext;
+  readonly args: readonly string[];
+  readonly stdout?: Writer;
+  readonly stderr?: Writer;
+  readonly adapter?: BacklogAdapter;
+  readonly resolveGitCommit?: (root: string) => string | null;
+  readonly generatedAt?: string | null;
+}
+
+export async function runExport(options: ExportOptions): Promise<number> {
+  const schemaVersion = parseExportArgs(options.args, options.output);
+  // Everything below this line may touch bundle, Backlog, or Git state. Keeping
+  // version parsing above it makes unsupported breaking versions fail first.
+  const profile = loadProfile({ root: options.root });
+  const warnings = new WarningCollector();
+  const graph = loadBundle(join(options.root, DOCS_DIR), { warnings, profile });
+  warnings.flush({ color: options.output.color, stderr: options.stderr });
+  const adapter = options.adapter ?? createBacklogAdapter(bunBacklogSpawn(undefined, options.root));
+  const tasks = await adapter.listTasks();
+  const gitCommit = (options.resolveGitCommit ?? resolveHeadSha)(options.root);
+  const projection = buildProjection({
+    graph,
+    tasks,
+    docsRoot: DOCS_DIR,
+    okfVersion: profile.okfVersion,
+    exporterVersion: VERSION,
+    gitCommit,
+    generatedAt:
+      options.generatedAt !== undefined ? options.generatedAt : sourceDateEpoch(process.env.SOURCE_DATE_EPOCH),
+  });
+  if (options.output.mode === "json") {
+    const data = { projectionSchemaVersion: schemaVersion, records: projection.records };
+    const renderable: Renderable<typeof data> = {
+      kind: "projection.export",
+      data,
+      pretty: () => projection.jsonl,
+      plain: () => projection.jsonl,
+    };
+    emit(renderable, options.output, options.stdout);
+  } else {
+    (options.stdout ?? process.stdout).write(projection.jsonl);
+  }
+  return EXIT_OK;
+}
+
+function parseExportArgs(args: readonly string[], output: OutputContext): string {
+  void output;
+  const parsed = parseCommandArgs(args, "export");
+  if (parsed.positionals.length > 0) {
+    throw usage(`unexpected argument "${parsed.positionals[0]}"`, "run `lore export --help` to list options");
+  }
+  const rawVersion = singleOptionValue(parsed, "schema-version");
+  if (rawVersion === "") {
+    throw usage("--schema-version needs a value", `pass --schema-version ${PROJECTION_SCHEMA_VERSION}`);
+  }
+  const version = rawVersion ?? PROJECTION_SCHEMA_VERSION;
+  if (version !== PROJECTION_SCHEMA_VERSION) {
+    throw usage(
+      `unsupported projection schema version "${version}"`,
+      `this lore supports ${PROJECTION_SCHEMA_VERSION}`,
+    );
+  }
+  return version;
+}
+
+function sourceDateEpoch(raw: string | undefined): string | null {
+  if (raw === undefined || raw.trim() === "") return null;
+  const seconds = Number(raw);
+  if (!Number.isFinite(seconds) || seconds < 0) {
+    throw usage("SOURCE_DATE_EPOCH must be a non-negative number", "unset it or provide Unix epoch seconds");
+  }
+  return new Date(seconds * 1000).toISOString();
+}
+
+function usage(message: string, hint: string): LoreError {
+  return new LoreError("usage", message, hint);
+}