@beignet/cli 0.0.48 → 0.0.50

package/src/check.ts

@@ -1,4 +1,4 @@
-import { readFile } from "node:fs/promises";
+import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { createPainter } from "./ansi.js";
 import { detectPackageManager, spawnCommand } from "./db.js";
@@ -75,6 +75,7 @@ export async function checkApp(
   options: CheckAppOptions = {},
 ): Promise<CheckAppResult> {
   const targetDir = path.resolve(options.cwd ?? process.cwd());
+  const scripts = await readAppPackageScripts(targetDir);
   const runner = await detectPackageManager(targetDir);
   const steps: CheckStep[] = [];
   const record = (step: CheckStep): void => {
@@ -99,7 +100,6 @@ export async function checkApp(
     );
   }
 
-  const scripts = await readPackageScripts(targetDir);
   for (const script of scriptStepNames) {
     options.signal?.throwIfAborted();
     record(await scriptStep(targetDir, runner, script, scripts, options));
@@ -269,7 +269,7 @@ async function scriptStep(
   };
 }
 
-async function readPackageScripts(
+async function readAppPackageScripts(
   targetDir: string,
 ): Promise<Record<string, string>> {
   let source: string;
@@ -282,11 +282,59 @@ async function readPackageScripts(
   }
 
   const parsed = JSON.parse(source) as {
+    dependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
     scripts?: Record<string, string>;
   };
+  const dependencies = {
+    ...parsed.dependencies,
+    ...parsed.optionalDependencies,
+  };
+  if (
+    !["@beignet/core", "@beignet/next", "@beignet/web"].some(
+      (packageName) => dependencies[packageName] !== undefined,
+    )
+  ) {
+    throw new Error(
+      "package.json does not declare a Beignet runtime dependency. Run beignet check from a Beignet app root that depends on @beignet/core, @beignet/next, or @beignet/web.",
+    );
+  }
+  if (!(await hasBeignetAppStructure(targetDir))) {
+    throw new Error(
+      "package.json declares a Beignet runtime dependency, but no Beignet app structure was found. Run beignet check from an app root containing app-context.ts, beignet.config.*, or features/ with server/index.ts.",
+    );
+  }
   return parsed.scripts ?? {};
 }
 
+async function hasBeignetAppStructure(targetDir: string): Promise<boolean> {
+  const entries = await readdir(targetDir, { withFileTypes: true });
+  const entryByName = new Map(entries.map((entry) => [entry.name, entry]));
+  if (entryByName.get("app-context.ts")?.isFile()) return true;
+  if (
+    [
+      "beignet.config.ts",
+      "beignet.config.json",
+      "beignet.config.mjs",
+      "beignet.config.js",
+    ].some((file) => entryByName.get(file)?.isFile())
+  ) {
+    return true;
+  }
+  if (
+    !entryByName.get("features")?.isDirectory() ||
+    !entryByName.get("server")?.isDirectory()
+  ) {
+    return false;
+  }
+
+  try {
+    return (await stat(path.join(targetDir, "server/index.ts"))).isFile();
+  } catch {
+    return false;
+  }
+}
+
 async function preflightStep(
   targetDir: string,
   options: {

package/src/explain.ts

@@ -795,7 +795,7 @@ const conventionsByTargetKind = {
   ],
   job: [
     "Jobs represent background work and remain explicit at provider-backed execution boundaries.",
-    "Feature jobs register through central runtime or outbox registries before workers can dispatch them.",
+    "Feature jobs register through central runtime or outbox registries before workers can dispatch them; registration does not install the required jobs port.",
   ],
   schedule: [
     "Schedules represent time-based triggers and delegate work to application workflows.",
@@ -819,11 +819,11 @@ const conventionsByTargetKind = {
   ],
   registry: [
     "Registries explicitly compose feature declarations into the runtime surface inspected by doctor and app-map.",
-    "Central registries remain the source of truth for runtime wiring and integrity checks.",
+    "Central registries remain the source of truth for runtime wiring and integrity checks; outbox registries containing jobs depend on a bound or deferred jobs dispatcher.",
   ],
   port: [
     "Ports define app-facing dependency interfaces; infrastructure adapters provide their concrete implementations.",
-    "App ports wire through infra/port-wiring.ts and remain available to use cases through application context.",
+    "App ports wire through the configured port-wiring file and remain available to use cases through application context; deferred ports are verified during server startup.",
   ],
   provider: [
     "Ports define app-facing interfaces, providers adapt external systems, and app infrastructure wires them together.",
@@ -839,7 +839,7 @@ const conventionsByTargetKind = {
   ],
   entrypoint: [
     "Runtime entrypoints compose the server or expose thin framework adapters over registered routes.",
-    "Entrypoints reuse central context, routes, providers, and workflow registries instead of duplicating application behavior.",
+    "Entrypoints reuse central context, routes, providers, and workflow registries instead of duplicating application behavior; outbox drains require delivery ports before they claim messages.",
   ],
   test: [
     "Feature behavior tests stay under features/<feature>/tests and exercise use cases, routes, policies, workflows, and UI.",

package/src/git-changes.ts

@@ -0,0 +1,511 @@
+import { createHash } from "node:crypto";
+import type { Stats } from "node:fs";
+import { createReadStream } from "node:fs";
+import { lstat, readlink } from "node:fs/promises";
+import path from "node:path";
+import { spawnCommand } from "./db.js";
+
+const emptyTreeObjectIds = {
+  sha1: "4b825dc642cb6eb9a060e54bf8d69288fbee4904",
+  sha256: "6ef19b41225c5369f1c104d45d8d85efa9b057b53b14b4b9b939dd74decc5321",
+} as const;
+const maxGitOutputBytes = 64 * 1024 * 1024;
+
+type GitCommandResult = Omit<
+  Awaited<ReturnType<typeof spawnCommand>>,
+  "stderr" | "stdout"
+> & {
+  stderr: string;
+  stdout: string;
+};
+
+/** Git status values represented by changed-app mapping. */
+export type GitChangedFileStatus =
+  | "added"
+  | "copied"
+  | "deleted"
+  | "modified"
+  | "renamed"
+  | "type-changed"
+  | "unmerged"
+  | "unknown"
+  | "untracked";
+
+export type GitChangedFile = {
+  status: GitChangedFileStatus;
+  path: string;
+  oldPath?: string;
+};
+
+/** Resolved local Git comparison used by changed-app mapping. */
+export type GitChangeComparison =
+  | {
+      mode: "worktree";
+      comparisonCommit: string;
+      head?: string;
+    }
+  | {
+      mode: "base";
+      base: string;
+      baseCommit: string;
+      mergeBase: string;
+      head: string;
+    };
+
+export type GitChangeSet = {
+  repositoryRoot: string;
+  comparison: GitChangeComparison;
+  files: GitChangedFile[];
+};
+
+export async function readGitChangeSet(options: {
+  cwd: string;
+  base?: string;
+}): Promise<GitChangeSet> {
+  if (options.base !== undefined && options.base.length === 0) {
+    throw new Error("Git base must not be empty.");
+  }
+  const repositoryRoot = path.resolve(
+    await gitText(options.cwd, ["rev-parse", "--show-toplevel"]),
+  );
+  const head = await resolveHeadCommit(repositoryRoot);
+
+  let comparison: GitChangeComparison;
+  let comparisonCommit: string;
+  if (options.base !== undefined) {
+    if (!head) {
+      throw new Error(
+        `Cannot compare --base ${JSON.stringify(options.base)} because this repository does not have a HEAD commit.`,
+      );
+    }
+    const baseCommit = await gitText(repositoryRoot, [
+      "rev-parse",
+      "--verify",
+      "--end-of-options",
+      `${options.base}^{commit}`,
+    ]).catch(() => {
+      throw new Error(
+        `Could not resolve local Git base ${JSON.stringify(options.base)}. Fetch it before running Beignet; changed mapping never accesses the network.`,
+      );
+    });
+    const mergeBase = await gitText(repositoryRoot, [
+      "merge-base",
+      baseCommit,
+      head,
+    ]).catch(() => {
+      throw new Error(
+        `Could not find a merge base between ${JSON.stringify(options.base)} and HEAD.`,
+      );
+    });
+    comparisonCommit = mergeBase;
+    comparison = {
+      mode: "base",
+      base: options.base,
+      baseCommit,
+      mergeBase,
+      head,
+    };
+  } else {
+    comparisonCommit = head ?? (await emptyTreeObjectId(repositoryRoot));
+    comparison = {
+      mode: "worktree",
+      comparisonCommit,
+      ...(head ? { head } : {}),
+    };
+  }
+
+  const committed =
+    comparison.mode === "base"
+      ? await gitDiffOutput(repositoryRoot, [
+          comparison.mergeBase,
+          comparison.head,
+        ])
+      : "";
+  const staged = await gitDiffOutput(repositoryRoot, [
+    "--cached",
+    head ?? comparisonCommit,
+  ]);
+  const unstaged = await gitDiffOutput(repositoryRoot, []);
+  const untracked = await gitOutput(repositoryRoot, [
+    "ls-files",
+    "--others",
+    "--exclude-standard",
+    "-z",
+  ]);
+  const files = mergeChangedFiles(
+    parseNameStatus(committed),
+    parseNameStatus(staged),
+    parseNameStatus(unstaged),
+    parseUntracked(untracked),
+  );
+
+  return { repositoryRoot, comparison, files };
+}
+
+async function emptyTreeObjectId(repositoryRoot: string): Promise<string> {
+  const objectFormat =
+    (await tryGitText(repositoryRoot, [
+      "rev-parse",
+      "--show-object-format=storage",
+    ])) ?? "sha1";
+  const objectId =
+    emptyTreeObjectIds[objectFormat as keyof typeof emptyTreeObjectIds];
+  if (!objectId) {
+    throw new Error(
+      `Unsupported Git object format ${JSON.stringify(objectFormat)}.`,
+    );
+  }
+  return objectId;
+}
+
+export async function hashGitChanges(
+  changeSet: Pick<GitChangeSet, "comparison" | "files" | "repositoryRoot">,
+  files = changeSet.files,
+): Promise<string> {
+  const hash = createHash("sha256");
+  const indexEntries = await readGitIndexEntries(changeSet.repositoryRoot);
+  hash.update(JSON.stringify(changeSet.comparison));
+  hash.update("\0");
+
+  for (const file of [...files].sort(compareChangedFiles)) {
+    hash.update(
+      JSON.stringify({
+        status: file.status,
+        path: file.path,
+        oldPath: file.oldPath,
+      }),
+    );
+    hash.update("\0");
+    for (const relativePath of uniquePaths([file.path, file.oldPath])) {
+      hash.update(relativePath);
+      hash.update("\0index\0");
+      hash.update(indexEntries.get(relativePath) ?? "missing");
+      hash.update("\0worktree\0");
+      await hashCurrentPath(hash, changeSet.repositoryRoot, relativePath);
+      hash.update("\0");
+    }
+  }
+
+  return `sha256:${hash.digest("hex")}`;
+}
+
+async function readGitIndexEntries(
+  repositoryRoot: string,
+): Promise<Map<string, string>> {
+  const output = await gitOutput(repositoryRoot, ["ls-files", "--stage", "-z"]);
+  const entries = new Map<string, string[]>();
+  for (const field of output.split("\0").filter(Boolean)) {
+    const separator = field.indexOf("\t");
+    if (separator === -1) {
+      throw new Error("Git returned an incomplete index entry.");
+    }
+    const metadata = field.slice(0, separator);
+    const file = normalizeGitPath(field.slice(separator + 1));
+    const values = entries.get(file) ?? [];
+    values.push(metadata);
+    entries.set(file, values);
+  }
+  return new Map(
+    [...entries].map(([file, values]) => [file, [...values].sort().join("\0")]),
+  );
+}
+
+async function hashCurrentPath(
+  hash: ReturnType<typeof createHash>,
+  repositoryRoot: string,
+  relativePath: string,
+): Promise<void> {
+  const absolutePath = path.join(repositoryRoot, relativePath);
+  let stats: Stats;
+  try {
+    stats = await lstat(absolutePath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      hash.update("missing");
+      return;
+    }
+    throw error;
+  }
+
+  if (stats.isSymbolicLink()) {
+    hash.update("symlink\0");
+    hash.update(String(stats.mode));
+    hash.update("\0");
+    hash.update(await readlink(absolutePath));
+    return;
+  }
+  if (stats.isDirectory()) {
+    hash.update("directory\0");
+    const head = await tryGitText(absolutePath, [
+      "rev-parse",
+      "--verify",
+      "HEAD^{commit}",
+    ]);
+    const status = await tryGitOutput(absolutePath, [
+      "status",
+      "--porcelain=v1",
+      "-z",
+      "--untracked-files=all",
+    ]);
+    hash.update(head ?? "unknown-head");
+    hash.update("\0");
+    hash.update(status ?? "unknown-status");
+    return;
+  }
+  if (!stats.isFile()) {
+    hash.update("special");
+    return;
+  }
+
+  hash.update("file\0");
+  hash.update(String(stats.mode));
+  hash.update("\0");
+  for await (const chunk of createReadStream(absolutePath)) {
+    hash.update(chunk as Buffer);
+  }
+}
+
+function parseNameStatus(output: string): GitChangedFile[] {
+  if (!output) return [];
+  const fields = output.split("\0");
+  const files: GitChangedFile[] = [];
+  for (let index = 0; index < fields.length; ) {
+    const rawStatus = fields[index++];
+    if (!rawStatus) continue;
+    const status = changedFileStatus(rawStatus[0]);
+    if (status === "renamed" || status === "copied") {
+      const oldPath = fields[index++];
+      const nextPath = fields[index++];
+      if (!oldPath || !nextPath) {
+        throw new Error("Git returned an incomplete rename or copy record.");
+      }
+      files.push({
+        status,
+        oldPath: normalizeGitPath(oldPath),
+        path: normalizeGitPath(nextPath),
+      });
+      continue;
+    }
+    const file = fields[index++];
+    if (!file)
+      throw new Error("Git returned an incomplete changed-file record.");
+    files.push({ status, path: normalizeGitPath(file) });
+  }
+  return files;
+}
+
+function parseUntracked(output: string): GitChangedFile[] {
+  return output
+    .split("\0")
+    .filter(Boolean)
+    .map((file) => ({ status: "untracked", path: normalizeGitPath(file) }));
+}
+
+function mergeChangedFiles(...groups: GitChangedFile[][]): GitChangedFile[] {
+  const files = new Map<string, GitChangedFile>();
+  for (const group of groups) {
+    for (const file of group) {
+      if (file.status === "renamed" && file.oldPath) {
+        const source = files.get(file.oldPath);
+        if (source) {
+          files.delete(file.oldPath);
+          const composed = composeRename(source, file);
+          files.set(
+            composed.path,
+            mergeSameDestination(files.get(composed.path), composed),
+          );
+          continue;
+        }
+      }
+      files.set(file.path, mergeSameDestination(files.get(file.path), file));
+    }
+  }
+  return [...files.values()].sort(compareChangedFiles);
+}
+
+function composeRename(
+  source: GitChangedFile,
+  rename: GitChangedFile,
+): GitChangedFile {
+  if (source.status === "renamed" && source.oldPath) {
+    return rename.path === source.oldPath
+      ? source
+      : { status: "renamed", oldPath: source.oldPath, path: rename.path };
+  }
+  if (source.status === "copied" && source.oldPath) {
+    return { status: "copied", oldPath: source.oldPath, path: rename.path };
+  }
+  if (source.status === "added" || source.status === "untracked") {
+    return { status: source.status, path: rename.path };
+  }
+  return rename;
+}
+
+function mergeSameDestination(
+  previous: GitChangedFile | undefined,
+  next: GitChangedFile,
+): GitChangedFile {
+  if (
+    previous &&
+    (previous.status === "added" ||
+      previous.status === "copied" ||
+      previous.status === "renamed" ||
+      previous.status === "untracked") &&
+    next.status !== "unmerged" &&
+    next.status !== "unknown"
+  ) {
+    return previous;
+  }
+  return next;
+}
+
+function uniquePaths(paths: Array<string | undefined>): string[] {
+  return [...new Set(paths.filter((file): file is string => Boolean(file)))];
+}
+
+function changedFileStatus(status: string | undefined): GitChangedFileStatus {
+  switch (status) {
+    case "A":
+      return "added";
+    case "C":
+      return "copied";
+    case "D":
+      return "deleted";
+    case "M":
+      return "modified";
+    case "R":
+      return "renamed";
+    case "T":
+      return "type-changed";
+    case "U":
+      return "unmerged";
+    default:
+      return "unknown";
+  }
+}
+
+function compareChangedFiles(
+  left: GitChangedFile,
+  right: GitChangedFile,
+): number {
+  return `${left.path}\0${left.oldPath ?? ""}\0${left.status}`.localeCompare(
+    `${right.path}\0${right.oldPath ?? ""}\0${right.status}`,
+  );
+}
+
+function normalizeGitPath(file: string): string {
+  return process.platform === "win32" ? file.replaceAll("\\", "/") : file;
+}
+
+async function gitText(cwd: string, args: readonly string[]): Promise<string> {
+  return (await gitOutput(cwd, args)).trim();
+}
+
+async function resolveHeadCommit(
+  repositoryRoot: string,
+): Promise<string | undefined> {
+  const head = await runGit(repositoryRoot, [
+    "rev-parse",
+    "--verify",
+    "HEAD^{commit}",
+  ]);
+  if (head.exitCode === 0) return head.stdout.trim();
+
+  const symbolicHead = await runGit(repositoryRoot, [
+    "symbolic-ref",
+    "--quiet",
+    "HEAD",
+  ]);
+  if (symbolicHead.exitCode !== 0) {
+    throw gitCommandError(["rev-parse", "--verify", "HEAD^{commit}"], head);
+  }
+
+  const ref = symbolicHead.stdout.trim();
+  const refExists = await runGit(repositoryRoot, [
+    "show-ref",
+    "--verify",
+    "--quiet",
+    ref,
+  ]);
+  if (refExists.exitCode === 1) return undefined;
+  throw gitCommandError(["rev-parse", "--verify", "HEAD^{commit}"], head);
+}
+
+async function tryGitText(
+  cwd: string,
+  args: readonly string[],
+): Promise<string | undefined> {
+  try {
+    return await gitText(cwd, args);
+  } catch {
+    return undefined;
+  }
+}
+
+async function tryGitOutput(
+  cwd: string,
+  args: readonly string[],
+): Promise<string | undefined> {
+  try {
+    return await gitOutput(cwd, args);
+  } catch {
+    return undefined;
+  }
+}
+
+async function gitOutput(
+  cwd: string,
+  args: readonly string[],
+): Promise<string> {
+  const result = await runGit(cwd, args);
+  if (result.exitCode !== 0) throw gitCommandError(args, result);
+  return result.stdout;
+}
+
+async function runGit(
+  cwd: string,
+  args: readonly string[],
+): Promise<GitCommandResult> {
+  const result = await spawnCommand("git", args, cwd, {
+    captureOutput: true,
+    maxOutputBytes: maxGitOutputBytes,
+  });
+  if (result.outputTruncated) {
+    throw new Error(
+      `Git output exceeded ${maxGitOutputBytes} bytes; changed mapping cannot produce a complete report.`,
+    );
+  }
+  return {
+    ...result,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+  };
+}
+
+function gitCommandError(
+  args: readonly string[],
+  result: GitCommandResult,
+): Error {
+  const detail = result.stderr.trim() || result.stdout.trim();
+  return new Error(
+    `Git command failed: git ${args.join(" ")}${detail ? `\n${detail}` : ""}`,
+  );
+}
+
+async function gitDiffOutput(
+  repositoryRoot: string,
+  comparisonArgs: readonly string[],
+): Promise<string> {
+  return gitOutput(repositoryRoot, [
+    "diff",
+    "--no-ext-diff",
+    "--no-textconv",
+    "--name-status",
+    "-z",
+    "--find-renames=50%",
+    "--find-copies=50%",
+    "--find-copies-harder",
+    ...comparisonArgs,
+    "--",
+  ]);
+}

package/src/index.ts

@@ -120,6 +120,8 @@ type RoutesFlags = {
 type MapFlags = RoutesFlags & {
   feature?: string;
   kind?: readonly AppMapNodeKind[];
+  changed?: boolean;
+  base?: string;
 };
 
 type ExplainFlags = RoutesFlags;
@@ -391,6 +393,15 @@ const routesFlagParameters = {
 
 const mapFlagParameters = {
   json: jsonFlag,
+  changed: {
+    kind: "boolean",
+    optional: true,
+    withNegated: false,
+    brief: "Map the current Git change set to potentially affected concepts.",
+  },
+  base: parsedStringFlag(
+    "Include committed changes since the merge base of this local Git ref. Requires --changed.",
+  ),
   feature: parsedStringFlag(
     "Project one feature and its direct relationships.",
   ),
@@ -889,7 +900,7 @@ const mapCommand = buildCommand<MapFlags, [], CliContext>({
   docs: {
     brief: "Map the app's architecture and registered workflows.",
     fullDescription:
-      "Build a deterministic graph of features, HTTP contracts, routes, use cases, policies, workflows, ports, providers, OpenAPI, tests, dependencies, and doctor findings.",
+      "Build a deterministic graph of features, HTTP contracts, routes, use cases, policies, workflows, ports, providers, OpenAPI, tests, dependencies, and doctor findings. Use --changed for a bounded, report-only semantic map of the current Git change set.",
   },
   parameters: {
     flags: mapFlagParameters,
@@ -898,8 +909,35 @@ const mapCommand = buildCommand<MapFlags, [], CliContext>({
     const { formatAppMap, mapApp, projectAppMap } = await import(
       "./app-map.js"
     );
+    const { formatAppChangeImpact, mapAppChanges } = await import(
+      "./app-map-changes.js"
+    );
 
     return async function runMap(this: CliContext, flags: MapFlags) {
+      if (flags.base !== undefined && !flags.changed) {
+        throw new Error("map --base requires --changed.");
+      }
+      if (
+        flags.changed &&
+        (flags.feature !== undefined || flags.kind !== undefined)
+      ) {
+        throw new Error(
+          "map --changed cannot be combined with --feature or --kind.",
+        );
+      }
+      if (flags.changed) {
+        const changed = await mapAppChanges({
+          cwd: flags.cwd,
+          base: flags.base,
+        });
+        writeOutput(
+          this,
+          flags.json
+            ? JSON.stringify(changed, null, 2)
+            : formatAppChangeImpact(changed),
+        );
+        return;
+      }
       const result = projectAppMap(
         await mapApp({ cwd: flags.cwd, strict: true }),
         {