@opum-ai/lore 0.1.0 → 0.2.0

package/src/commands/traversal.ts

@@ -1,151 +0,0 @@
-/** Shared CLI parsing and rendering for bounded typed traversal commands. */
-
-import { idFromPath } from "../core/concept";
-import {
-  DEFAULT_TRAVERSAL_LIMIT,
-  DEFAULT_TRAVERSAL_MAX_DEPTH,
-  type ImpactResult,
-  MAX_TRAVERSAL_DEPTH,
-  MAX_TRAVERSAL_LIMIT,
-  type PathResult,
-  type TraversalDirection,
-  type TraversalEndpointKind,
-  type TraversalSnapshot,
-  type TraversalStep,
-} from "../core/traversal";
-import { parseQualifiedWorkspaceId, qualifyWorkspaceId } from "../core/workspace-contract";
-import { singleLine } from "../errors";
-import type { Renderable } from "../output";
-import { optionValues, type ParsedArgs, singleOptionValue, usage } from "./args";
-
-export interface TraversalFlags {
-  readonly direction: TraversalDirection;
-  readonly edgeKinds?: readonly string[];
-  readonly maxDepth: number;
-  readonly limit: number;
-}
-
-export function parseTraversalFlags(parsed: ParsedArgs): TraversalFlags {
-  const direction = requiredChoice(parsed, "direction", ["outbound", "inbound", "either"] as const);
-  const edgeKinds = optionValues(parsed, "edge").map((value) => requiredValue("edge", value));
-  if (new Set(edgeKinds).size !== edgeKinds.length) {
-    throw usage("--edge values must be unique", "pass each authored edge kind at most once");
-  }
-  const maxDepth = boundedInteger(parsed, "max-depth", DEFAULT_TRAVERSAL_MAX_DEPTH, 0, MAX_TRAVERSAL_DEPTH);
-  const limit = boundedInteger(parsed, "limit", DEFAULT_TRAVERSAL_LIMIT, 1, MAX_TRAVERSAL_LIMIT);
-  return {
-    direction,
-    ...(edgeKinds.length > 0 ? { edgeKinds } : {}),
-    maxDepth,
-    limit,
-  };
-}
-
-export function parseEndpointKind(parsed: ParsedArgs, name: string): TraversalEndpointKind {
-  return requiredChoice(parsed, name, ["concept", "task"] as const);
-}
-
-export function normalizeEndpointId(raw: string, kind: TraversalEndpointKind, workspace: boolean): string {
-  const value = raw.trim();
-  if (value === "") throw usage("endpoint id must not be empty", "pass a concept or task id");
-  if (!workspace) return kind === "concept" ? idFromPath(value) : value;
-  try {
-    const parsed = parseQualifiedWorkspaceId(value);
-    return qualifyWorkspaceId(parsed.memberId, kind === "concept" ? idFromPath(parsed.sourceId) : parsed.sourceId);
-  } catch {
-    throw usage(`invalid workspace ${kind} id "${value}"`, "use the unambiguous <member-id>::<source-id> form");
-  }
-}
-
-export function assertKnownEdgeKinds(snapshot: TraversalSnapshot, requested?: readonly string[]): void {
-  if (requested === undefined) return;
-  const known = new Set(snapshot.edges.map((edge) => edge.kind));
-  const unknown = requested.find((kind) => !known.has(kind));
-  if (unknown !== undefined) {
-    throw usage(`unknown authored edge kind "${unknown}"`, "omit --edge to traverse all authored edge kinds");
-  }
-}
-
-export function pathRenderable(data: PathResult): Renderable<PathResult> {
-  return { kind: "path.result", data, pretty: renderPaths, plain: renderPaths };
-}
-
-export function impactRenderable(data: ImpactResult): Renderable<ImpactResult> {
-  return {
-    kind: "impact.result",
-    data,
-    pretty: renderImpact,
-    plain: renderImpact,
-  };
-}
-
-function renderPaths(data: PathResult): string {
-  const header = `${data.shown} path${data.shown === 1 ? "" : "s"} from ${typed(data.from.kind, data.from.id)} to ${typed(data.to.kind, data.to.id)}`;
-  const lines = data.paths.map((path, index) => `${index + 1}. ${renderChain(path.edges, data.from.id)}`);
-  return `${[...lines, header, accounting(data)].join("\n")}\n`;
-}
-
-function renderImpact(data: ImpactResult): string {
-  const lines = data.impacts.map(
-    (impact) =>
-      `${typed(impact.endpoint.kind, impact.endpoint.id)}  ${impact.relationship}  depth ${impact.depth}  via ${renderChain(impact.evidence, data.root.id)}`,
-  );
-  const header = `${data.shown} impact${data.shown === 1 ? "" : "s"} from ${typed(data.root.kind, data.root.id)}`;
-  return `${[...lines, header, accounting(data)].join("\n")}\n`;
-}
-
-function renderChain(steps: readonly TraversalStep[], rootId: string): string {
-  if (steps.length === 0) return singleLine(rootId);
-  return [
-    singleLine(rootId),
-    ...steps.flatMap((step) => [
-      step.direction === "outbound" ? `-${singleLine(step.edge.kind)}->` : `<-${singleLine(step.edge.kind)}-`,
-      singleLine(step.to.id),
-    ]),
-  ].join(" ");
-}
-
-function accounting(data: PathResult | ImpactResult): string {
-  return `depth<=${data.limits.maxDepth}, edge-visits=${data.edgeVisits}/${data.limits.maxEdgeVisits}, complete=${String(data.complete)}, truncated=${String(data.truncated)}`;
-}
-
-function typed(kind: TraversalEndpointKind, id: string): string {
-  return `${kind}:${singleLine(id)}`;
-}
-
-function requiredValue(name: string, raw: string): string {
-  const value = raw.trim();
-  if (value === "") throw usage(`--${name} needs a value`, `pass --${name}=<value>`);
-  return value;
-}
-
-function requiredChoice<const T extends readonly string[]>(parsed: ParsedArgs, name: string, values: T): T[number] {
-  const raw = singleOptionValue(parsed, name);
-  if (raw === undefined || raw.trim() === "") {
-    throw usage(`--${name} is required`, `pass --${name} <${values.join("|")}>`);
-  }
-  const value = raw.trim();
-  if (!values.includes(value)) {
-    throw usage(`invalid --${name} "${value}"`, `choose one of ${values.join(", ")}`);
-  }
-  return value as T[number];
-}
-
-function boundedInteger(
-  parsed: ParsedArgs,
-  name: string,
-  defaultValue: number,
-  minimum: number,
-  maximum: number,
-): number {
-  const raw = singleOptionValue(parsed, name);
-  if (raw === undefined) return defaultValue;
-  if (!/^\d+$/u.test(raw)) {
-    throw usage(`invalid --${name} "${raw}"`, `pass an integer from ${minimum} through ${maximum}`);
-  }
-  const value = Number.parseInt(raw, 10);
-  if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
-    throw usage(`--${name} must be between ${minimum} and ${maximum}`, `pass an integer no greater than ${maximum}`);
-  }
-  return value;
-}

package/src/commands/validate.ts

@@ -1,226 +0,0 @@
-/**
- * commands/validate.ts — `lore validate [paths…]`: tiered per-file conformance reporting.
- *
- * The thin, side-effecting layer over the pure {@link validateFiles} engine (ADR-0007,
- * cli-surface §validate): it parses the command's own arguments, **discovers** the files to
- * check (a default whole-bundle walk, or the explicit `[paths…]` a pre-commit hook passes —
- * LORE-19 AC#2), reads their bytes, asks core for the tiered findings, renders the report, and
- * returns the exit code. All file discovery and I/O live here; all judgement lives in
- * `core/validate.ts`.
- *
- * Unlike `init`/`new`, a content failure is **not** a thrown {@link LoreError}: `validate` is a
- * reporter, so it emits the full `validate.report` on stdout and then *returns* exit `6` when any
- * error-tier finding exists (or any warning under `--strict`) — the report is the payload, the
- * exit code is the gate signal. Only a *usage* error (bad flag) or an *I/O* failure (an
- * unreadable path) throws, funneling through the router's one error seam like every command.
- */
-
-import { statSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { walkMarkdown } from "../core/bundle";
-import { loadProfile } from "../core/profile";
-import { DOCS_DIR } from "../core/scaffold";
-import { canonicalType } from "../core/schema";
-import { type FileReport, type Finding, type ValidateReport, validateFiles } from "../core/validate";
-import { ANSI, EXIT_CODES, EXIT_OK, ioError, LoreError, paint, WarningCollector, type Writer } from "../errors";
-import { emit, type OutputContext, type Renderable } from "../output";
-import { assertFlagAtMostOnce, parseCommandArgs, singleOptionValue } from "./args";
-import { canonicalIdentity, readSource, toRepoRelative } from "./discover";
-
-/** Options for {@link runValidate}; `root` and the streams are injectable for tests. */
-export interface ValidateOptions {
-  /** The repo root the (relative) target paths resolve 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 discovery advisories (a skipped symlink, an unreadable sub-directory); defaults to `process.stderr`. */
-  stderr?: Writer;
-}
-
-/** The parsed form of `lore validate`'s arguments. */
-interface ValidateArgs {
-  /** Explicit target paths (files or directories); empty means the whole bundle. */
-  paths: string[];
-  /** `--type <T>`: limit the report to one concept type (canonical or case-insensitive). */
-  type?: string;
-  /** `--strict`: treat any warning as a failure for the exit code. */
-  strict: boolean;
-}
-
-/** A discovered file ready for the pure engine: its repo-relative path and raw bytes. */
-interface SourceFile {
-  path: string;
-  raw: string;
-}
-
-/**
- * Run `lore validate`: parse the arguments, discover and read the target files, validate them,
- * emit the `validate.report`, and return the exit code — `0` when clean (or warnings-only without
- * `--strict`), `6` when any error-tier finding exists (or any warning under `--strict`). A bad
- * flag throws a `usage` {@link LoreError} (exit `2`); an unreadable path a `not_found`/`denied`.
- *
- * Discovery advisories (a `.md` concept skipped behind a symlink, an unreadable sub-directory) are
- * flushed to stderr — never silently swallowed, so a run that omits files says so — but, like every
- * advisory, they do not change the exit code.
- */
-export function runValidate(options: ValidateOptions): number {
-  const parsed = parseValidateArgs(options.args);
-  const profile = loadProfile({ root: options.root });
-  const type = parsed.type === undefined ? undefined : canonicalType(parsed.type, profile);
-  const walkWarnings = new WarningCollector();
-  const files = collectFiles(options.root, parsed.paths, walkWarnings);
-
-  const report = validateFiles(files, type, profile);
-  emit(reportRenderable(report), options.output, options.stdout);
-  walkWarnings.flush({ color: options.output.color, stderr: options.stderr });
-
-  const failed = report.errorCount > 0 || (parsed.strict && report.warningCount > 0);
-  return failed ? EXIT_CODES.validation : EXIT_OK;
-}
-
-// ── Argument parsing ───────────────────────────────────────────────────────────
-
-/**
- * Parse `validate`'s tokens into target paths and its flags. Commander has already resolved
- * lore's global flags, so anything `--`-prefixed here is a command flag: an unrecognized one is a
- * `usage` error. Both `--flag value` and `--flag=value` forms are accepted; `--type`'s value must
- * not itself be a flag-looking token (so a mis-ordered `--type --strict` fails loud rather than
- * eating `--strict`). A `--` ends option parsing so a path may begin with `-`.
- */
-function parseValidateArgs(args: readonly string[]): ValidateArgs {
-  const parsed = parseCommandArgs(args, "validate");
-  const type = singleOptionValue(parsed, "type");
-  assertFlagAtMostOnce(parsed, "strict");
-  if (type !== undefined && type.trim() === "") {
-    throw usage("`--type` needs a value", "pass a type, e.g. --type ADR");
-  }
-  return { paths: parsed.positionals, type, strict: parsed.flags.has("strict") };
-}
-
-// ── File discovery ─────────────────────────────────────────────────────────────
-
-/**
- * Discover and read every file to validate. With no explicit paths the target is the whole
- * bundle (`docs/`); otherwise each path is taken verbatim — a **directory** is walked for `.md`
- * files (via the same {@link walkMarkdown} the bundle loader uses, so the walk is sorted,
- * symlink-safe, and `.md`-only — its skipped-symlink/unreadable-subdir advisories flow to
- * `warnings`), and a **file** is read directly even if it is not `.md` (the user named it
- * explicitly). Results are de-duplicated by the file's **canonical (realpath) identity**, so the
- * same physical file named twice — including via two casings on a case-insensitive filesystem, or
- * once directly and once under a walked directory — is validated and counted once.
- */
-function collectFiles(root: string, paths: readonly string[], warnings: WarningCollector): SourceFile[] {
-  const targets = paths.length > 0 ? paths : [DOCS_DIR];
-  const files: SourceFile[] = [];
-  const seen = new Set<string>();
-  for (const target of targets) {
-    const abs = resolve(root, target);
-    for (const absFile of expandTarget(abs, target, warnings)) {
-      const identity = canonicalIdentity(absFile);
-      if (seen.has(identity)) {
-        continue;
-      }
-      seen.add(identity);
-      const repoRel = toRepoRelative(root, absFile);
-      files.push({ path: repoRel, raw: readSource(absFile, repoRel) });
-    }
-  }
-  return files;
-}
-
-/**
- * Expand one target to the absolute file paths it names: a directory to every `.md` under it (a
- * sorted walk that does not follow symlinks *inside* the tree, routing its advisories to
- * `warnings`), a file to itself. A path that does not exist is a `not_found` {@link LoreError}
- * (exit `3`) naming the target the user gave, so a typo'd path fails loud rather than silently
- * validating nothing. An explicitly-named directory *is* followed through a top-level symlink
- * (the user named it); only links discovered beneath it are skipped, matching `loadBundle`.
- */
-function expandTarget(abs: string, target: string, warnings: WarningCollector): string[] {
-  let stat: ReturnType<typeof statSync>;
-  try {
-    stat = statSync(abs);
-  } catch (cause) {
-    ioError(cause, {
-      denied: { message: `cannot access "${target}"`, hint: "check filesystem permissions on that path" },
-      notFound: { message: `path "${target}" does not exist`, hint: "check the path and try again" },
-      input: { path: target },
-      rethrowUnknown: true,
-    });
-  }
-  if (stat.isDirectory()) {
-    return walkMarkdown(abs, warnings).map((rel) => join(abs, rel));
-  }
-  return [abs];
-}
-
-// ── Output ─────────────────────────────────────────────────────────────────────
-
-/** The per-result-type rendering bundle for `validate` (output.ts dispatches on the mode). */
-function reportRenderable(data: ValidateReport): Renderable<ValidateReport> {
-  return {
-    kind: "validate.report",
-    data,
-    // Pretty and plain are the same layout; only color differs (plain is always ANSI-free), so a
-    // single renderer keyed on the color flag keeps the two views from ever drifting.
-    pretty: (report, opts) => renderReport(report, opts.color),
-    plain: (report) => renderReport(report, false),
-  };
-}
-
-/** One line per finding (colored by severity), a per-file `ok`/`skip` status otherwise, then a summary. */
-function renderReport(data: ValidateReport, color: boolean): string {
-  const lines: string[] = [];
-  for (const file of data.files) {
-    lines.push(...fileLines(file, color));
-  }
-  lines.push(summaryLine(data, color));
-  return lines.join("\n");
-}
-
-/**
- * The lines for one file: a single `ok`/`skip` status when there is nothing to report, else one
- * line per finding (`error`/`warning` + path + `[rule]` + message). Color paints only the
- * severity token, so the line stays diff-stable in plain mode.
- */
-function fileLines(file: FileReport, color: boolean): string[] {
-  if (file.skipped) {
-    return [`${paint("skip", ANSI.dim, color)} ${file.path} (not a concept)`];
-  }
-  if (file.findings.length === 0) {
-    return [`${paint("ok", ANSI.green, color)} ${file.path}`];
-  }
-  return file.findings.map((finding) => findingLine(file.path, finding, color));
-}
-
-/** One finding line: `<severity> <path> [<rule>]: <message>`. */
-function findingLine(path: string, finding: Finding, color: boolean): string {
-  const tone = finding.severity === "error" ? ANSI.red : ANSI.yellow;
-  return `${paint(finding.severity, tone, color)} ${path} [${finding.rule}]: ${finding.message}`;
-}
-
-/** The trailing summary: file/error/warning/skip counts, the error count painted when nonzero. */
-function summaryLine(data: ValidateReport, color: boolean): string {
-  const errors = `${data.errorCount} ${plural(data.errorCount, "error")}`;
-  const painted = data.errorCount > 0 ? paint(errors, ANSI.red, color) : errors;
-  return [
-    `${data.files.length} ${plural(data.files.length, "file")}`,
-    painted,
-    `${data.warningCount} ${plural(data.warningCount, "warning")}`,
-    `${data.skippedCount} skipped`,
-  ].join(", ");
-}
-
-/** Pluralize a noun by count (`1 error`, `2 errors`). */
-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);
-}