patram 0.8.0 → 0.9.0

package/bin/patram.js

@@ -4,7 +4,7 @@ import { realpath } from 'node:fs/promises';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
-import { main } from '../lib/patram-cli.js';
+import { main } from '../lib/cli/main.js';
 
 /**
  * Patram CLI entrypoint.
@@ -17,7 +17,7 @@ import { main } from '../lib/patram-cli.js';
  * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
  * Decided by: ../docs/decisions/cli-entrypoint-symlink.md
  * @patram
- * @see {@link ../lib/patram-cli.js}
+ * @see {@link ../lib/cli/main.js}
  * @see {@link ../docs/patram.md}
  */
 

package/lib/{parse-cli-color-options.js → cli/color-options.js}

@@ -1,6 +1,6 @@
 /**
- * @typedef {import('./parse-cli-arguments-helpers.js').CliOptionToken} CliOptionToken
- * @typedef {import('./parse-cli-arguments.types.ts').CliColorMode} CliColorMode
+ * @typedef {import('./parse-arguments-helpers.js').CliOptionToken} CliOptionToken
+ * @typedef {import('./arguments.types.ts').CliColorMode} CliColorMode
  */
 
 const VALID_COLOR_MODES = new Set(['auto', 'always', 'never']);

package/lib/cli/command-helpers.js

@@ -0,0 +1,35 @@
+/** @import * as $k$$k$$l$output$l$output$j$view$k$types$k$ts from '../output/output-view.types.ts'; */
+import process from 'node:process';
+
+import { resolveOutputMode } from './resolve-output-mode.js';
+
+/**
+ * @param {import('./arguments.types.ts').ParsedCliCommandRequest} parsed_command
+ * @param {{ stdout: { isTTY?: boolean } }} io_context
+ * @returns {$k$$k$$l$output$l$output$j$view$k$types$k$ts.ResolvedOutputMode}
+ */
+export function resolveCommandOutputMode(parsed_command, io_context) {
+  return resolveOutputMode(parsed_command, {
+    is_tty: io_context.stdout.isTTY === true,
+    no_color: process.env.NO_COLOR !== undefined,
+    term: process.env.TERM,
+  });
+}
+
+/**
+ * @param {{ write(chunk: string): boolean }} output_stream
+ * @param {import('../config/load-patram-config.types.ts').PatramDiagnostic[]} diagnostics
+ */
+export function writeDiagnostics(output_stream, diagnostics) {
+  for (const diagnostic of diagnostics) {
+    output_stream.write(formatDiagnostic(diagnostic));
+  }
+}
+
+/**
+ * @param {import('../config/load-patram-config.types.ts').PatramDiagnostic} diagnostic
+ * @returns {string}
+ */
+function formatDiagnostic(diagnostic) {
+  return `${diagnostic.path}:${diagnostic.line}:${diagnostic.column} ${diagnostic.level} ${diagnostic.code} ${diagnostic.message}\n`;
+}

package/lib/cli/commands/check.js

@@ -0,0 +1,73 @@
+/**
+ * @import { ParsedCliCommandRequest } from '../arguments.types.ts';
+ */
+
+import { checkGraph } from '../../graph/check-graph.js';
+import { loadProjectGraph } from '../../graph/load-project-graph.js';
+import {
+  renderCheckDiagnostics,
+  renderCheckSuccess,
+} from '../../output/render-check-output.js';
+import {
+  resolveCheckTarget,
+  selectCheckTargetDiagnostics,
+  selectCheckTargetSourceFiles,
+} from '../../output/resolve-check-target.js';
+import { listRepoFiles } from '../../scan/list-repo-files.js';
+
+import { resolveCommandOutputMode } from '../command-helpers.js';
+
+/**
+ * @param {ParsedCliCommandRequest} parsed_command
+ * @param {{ stderr: { write(chunk: string): boolean }, stdout: { isTTY?: boolean, write(chunk: string): boolean }, write_paged_output?: (output_text: string) => Promise<void> }} io_context
+ * @returns {Promise<number>}
+ */
+export async function runCheckCommand(parsed_command, io_context) {
+  const output_mode = resolveCommandOutputMode(parsed_command, io_context);
+  const resolved_target = await resolveCheckTarget(
+    parsed_command.command_arguments[0],
+  );
+  const project_graph_result = await loadProjectGraph(
+    resolved_target.project_directory,
+  );
+  const repo_file_paths = await listRepoFiles(
+    resolved_target.project_directory,
+  );
+  const selected_source_file_paths = selectCheckTargetSourceFiles(
+    project_graph_result.source_file_paths,
+    resolved_target,
+  );
+
+  if (project_graph_result.diagnostics.length > 0) {
+    io_context.stderr.write(
+      renderCheckDiagnostics(project_graph_result.diagnostics, output_mode),
+    );
+
+    return 1;
+  }
+
+  const diagnostics = checkGraph(
+    project_graph_result.graph,
+    repo_file_paths,
+    project_graph_result.config,
+    project_graph_result.claims,
+  );
+  const selected_diagnostics = selectCheckTargetDiagnostics(
+    diagnostics,
+    resolved_target,
+  );
+
+  if (selected_diagnostics.length > 0) {
+    io_context.stderr.write(
+      renderCheckDiagnostics(selected_diagnostics, output_mode),
+    );
+
+    return 1;
+  }
+
+  io_context.stdout.write(
+    renderCheckSuccess(selected_source_file_paths.length, output_mode),
+  );
+
+  return 0;
+}

package/lib/cli/commands/fields.js

@@ -0,0 +1,57 @@
+/**
+ * @import { ParsedCliCommandRequest } from '../arguments.types.ts';
+ * @import { PatramRepoConfig } from '../../config/load-patram-config.types.ts';
+ */
+
+import process from 'node:process';
+
+import { loadPatramConfig } from '../../config/load-patram-config.js';
+import { writeRenderedCommandOutput } from '../../output/command-output.js';
+import { renderFieldDiscovery } from '../../output/render-field-discovery.js';
+import { discoverFields } from '../../scan/discover-fields.js';
+
+import { resolveCommandOutputMode } from '../command-helpers.js';
+
+/**
+ * @param {ParsedCliCommandRequest} parsed_command
+ * @param {{ stderr: { write(chunk: string): boolean }, stdout: { isTTY?: boolean, write(chunk: string): boolean } }} io_context
+ * @returns {Promise<number>}
+ */
+export async function runFieldsCommand(parsed_command, io_context) {
+  const output_mode = resolveCommandOutputMode(parsed_command, io_context);
+  const load_result = await loadPatramConfig(process.cwd());
+  const defined_field_names =
+    load_result.diagnostics.length === 0
+      ? collectDefinedDiscoveryNames(load_result.config)
+      : new Set();
+  const discovery_result = await discoverFields(process.cwd(), {
+    defined_field_names,
+  });
+
+  await writeRenderedCommandOutput(
+    io_context,
+    parsed_command,
+    renderFieldDiscovery(discovery_result, output_mode),
+  );
+
+  return 0;
+}
+
+/**
+ * @param {PatramRepoConfig | null} repo_config
+ * @returns {Set<string>}
+ */
+function collectDefinedDiscoveryNames(repo_config) {
+  /** @type {Set<string>} */
+  const defined_field_names = new Set();
+
+  for (const field_name of Object.keys(repo_config?.fields ?? {})) {
+    defined_field_names.add(field_name);
+  }
+
+  for (const relation_name of Object.keys(repo_config?.relations ?? {})) {
+    defined_field_names.add(relation_name);
+  }
+
+  return defined_field_names;
+}

package/lib/cli/commands/queries.js

@@ -0,0 +1,41 @@
+/**
+ * @import { ParsedCliCommandRequest } from '../arguments.types.ts';
+ */
+
+import process from 'node:process';
+
+import { loadPatramConfig } from '../../config/load-patram-config.js';
+import { writeCommandOutput } from '../../output/command-output.js';
+import { listQueries } from '../../output/list-queries.js';
+import { createOutputView } from '../../output/render-output-view.js';
+
+import { writeDiagnostics } from '../command-helpers.js';
+
+/**
+ * @param {ParsedCliCommandRequest} parsed_command
+ * @param {{ stderr: { write(chunk: string): boolean }, stdout: { isTTY?: boolean, write(chunk: string): boolean }, write_paged_output?: (output_text: string) => Promise<void> }} io_context
+ * @returns {Promise<number>}
+ */
+export async function runQueriesCommand(parsed_command, io_context) {
+  const load_result = await loadPatramConfig(process.cwd());
+
+  if (load_result.diagnostics.length > 0) {
+    writeDiagnostics(io_context.stderr, load_result.diagnostics);
+
+    return 1;
+  }
+
+  const repo_config = load_result.config;
+
+  if (!repo_config) {
+    throw new Error('Expected a valid Patram repo config.');
+  }
+
+  await writeCommandOutput(
+    io_context,
+    parsed_command,
+    createOutputView('queries', listQueries(repo_config.queries)),
+  );
+
+  return 0;
+}

package/lib/cli/commands/query.js

@@ -0,0 +1,239 @@
+/**
+ * @import { ParsedCliCommandRequest } from '../arguments.types.ts';
+ * @import { GraphNode } from '../../graph/build-graph.types.ts';
+ * @import { ResolvedOutputMode } from '../../output/output-view.types.ts';
+ */
+
+import process from 'node:process';
+
+import {
+  shouldPageCommandOutput,
+  writeCommandOutput,
+} from '../../output/command-output.js';
+import { createDerivedSummaryEvaluator } from '../../output/derived-summary.js';
+import { renderCheckDiagnostics } from '../../output/render-check-output.js';
+import { renderInvalidWhereDiagnostic } from '../render-help.js';
+import { createOutputView } from '../../output/render-output-view.js';
+import { loadPatramConfig } from '../../config/load-patram-config.js';
+import { loadProjectGraph } from '../../graph/load-project-graph.js';
+import { DEFAULT_QUERY_LIMIT, queryGraph } from '../../graph/query/execute.js';
+import {
+  inspectQuery,
+  renderQueryInspection,
+} from '../../graph/query/inspect.js';
+import { resolveWhereClause } from '../../graph/query/resolve.js';
+
+import {
+  resolveCommandOutputMode,
+  writeDiagnostics,
+} from '../command-helpers.js';
+
+/**
+ * @param {ParsedCliCommandRequest} parsed_command
+ * @param {{ stderr: { write(chunk: string): boolean }, stdout: { isTTY?: boolean, write(chunk: string): boolean }, write_paged_output?: (output_text: string) => Promise<void> }} io_context
+ * @returns {Promise<number>}
+ */
+export async function runQueryCommand(parsed_command, io_context) {
+  const use_pager = shouldPageCommandOutput(parsed_command, io_context.stdout);
+  const output_mode = resolveCommandOutputMode(parsed_command, io_context);
+
+  if (parsed_command.query_inspection_mode) {
+    return runQueryInspectionCommand(
+      parsed_command,
+      io_context,
+      output_mode,
+      use_pager,
+    );
+  }
+
+  const project_graph_result = await loadProjectGraph(process.cwd());
+
+  if (project_graph_result.diagnostics.length > 0) {
+    writeDiagnostics(io_context.stderr, project_graph_result.diagnostics);
+
+    return 1;
+  }
+
+  const where_clause = resolveWhereClause(
+    project_graph_result.config,
+    parsed_command.command_arguments,
+  );
+
+  if (!where_clause.success) {
+    io_context.stderr.write(`${where_clause.message}\n`);
+
+    return 1;
+  }
+
+  const query_result = queryGraph(
+    project_graph_result.graph,
+    where_clause.value.where_clause,
+    project_graph_result.config,
+    createQueryPaginationOptions(parsed_command, use_pager),
+  );
+
+  if (query_result.diagnostics.length > 0) {
+    io_context.stderr.write(
+      renderInvalidWhereDiagnostic(query_result.diagnostics[0]),
+    );
+
+    return 1;
+  }
+
+  const derived_summary_evaluator = createDerivedSummaryEvaluator(
+    project_graph_result.config,
+    project_graph_result.graph,
+  );
+
+  await writeCommandOutput(
+    io_context,
+    parsed_command,
+    createOutputView('query', query_result.nodes, {
+      derived_summary_evaluator,
+      ...createQueryOutputOptions(parsed_command, query_result, use_pager),
+      repo_config: project_graph_result.config,
+    }),
+  );
+
+  return 0;
+}
+
+/**
+ * @param {ParsedCliCommandRequest} parsed_command
+ * @param {{ stderr: { write(chunk: string): boolean }, stdout: { isTTY?: boolean, write(chunk: string): boolean } }} io_context
+ * @param {ResolvedOutputMode} output_mode
+ * @param {boolean} use_pager
+ * @returns {Promise<number>}
+ */
+async function runQueryInspectionCommand(
+  parsed_command,
+  io_context,
+  output_mode,
+  use_pager,
+) {
+  const query_inspection_mode = parsed_command.query_inspection_mode;
+
+  if (!query_inspection_mode) {
+    throw new Error('Expected a query inspection mode.');
+  }
+
+  const load_result = await loadPatramConfig(process.cwd());
+
+  if (load_result.diagnostics.length > 0) {
+    io_context.stderr.write(
+      renderCheckDiagnostics(load_result.diagnostics, output_mode),
+    );
+
+    return 1;
+  }
+
+  const repo_config = load_result.config;
+
+  if (!repo_config) {
+    throw new Error('Expected a valid Patram repo config.');
+  }
+
+  const where_clause = resolveWhereClause(
+    repo_config,
+    parsed_command.command_arguments,
+  );
+
+  if (!where_clause.success) {
+    io_context.stderr.write(`${where_clause.message}\n`);
+
+    return 1;
+  }
+
+  const query_inspection = inspectQuery(repo_config, where_clause.value, {
+    inspection_mode: query_inspection_mode,
+    ...createQueryExecutionOptions(parsed_command, use_pager),
+  });
+
+  if (!query_inspection.success) {
+    io_context.stderr.write(
+      renderCheckDiagnostics(query_inspection.diagnostics, output_mode),
+    );
+
+    return 1;
+  }
+
+  io_context.stdout.write(
+    renderQueryInspection(query_inspection.value, output_mode),
+  );
+
+  return 0;
+}
+
+/**
+ * @param {ParsedCliCommandRequest} parsed_command
+ * @param {{ total_count: number, nodes: GraphNode[] }} query_result
+ * @param {boolean} use_pager
+ * @returns {{ hints: string[], limit: number, offset: number, total_count: number }}
+ */
+function createQueryOutputOptions(parsed_command, query_result, use_pager) {
+  /** @type {string[]} */
+  const hints = [];
+  const limit =
+    parsed_command.query_limit ??
+    (use_pager ? query_result.nodes.length : DEFAULT_QUERY_LIMIT);
+  const offset = parsed_command.query_offset ?? 0;
+
+  if (query_result.total_count === 0) {
+    hints.push("Try: patram query --where '$class=task'");
+  }
+
+  if (
+    !use_pager &&
+    parsed_command.query_limit === undefined &&
+    parsed_command.query_offset === undefined &&
+    query_result.total_count > DEFAULT_QUERY_LIMIT
+  ) {
+    hints.push(
+      'Hint: use --offset <n> or --limit <n> to page through more matches.',
+    );
+  }
+
+  return {
+    hints,
+    limit,
+    offset,
+    total_count: query_result.total_count,
+  };
+}
+
+/**
+ * @param {ParsedCliCommandRequest} parsed_command
+ * @param {boolean} use_pager
+ * @returns {{ limit?: number, offset: number }}
+ */
+function createQueryPaginationOptions(parsed_command, use_pager) {
+  /** @type {{ limit?: number, offset: number }} */
+  const pagination_options = {
+    offset: parsed_command.query_offset ?? 0,
+  };
+
+  if (parsed_command.query_limit !== undefined) {
+    pagination_options.limit = parsed_command.query_limit;
+  } else if (!use_pager) {
+    pagination_options.limit = DEFAULT_QUERY_LIMIT;
+  }
+
+  return pagination_options;
+}
+
+/**
+ * @param {ParsedCliCommandRequest} parsed_command
+ * @param {boolean} use_pager
+ * @returns {{ limit: number | null, offset: number }}
+ */
+function createQueryExecutionOptions(parsed_command, use_pager) {
+  const pagination_options = createQueryPaginationOptions(
+    parsed_command,
+    use_pager,
+  );
+
+  return {
+    limit: pagination_options.limit ?? null,
+    offset: pagination_options.offset,
+  };
+}

package/lib/cli/commands/refs.js

@@ -0,0 +1,72 @@
+/**
+ * @import { ParsedCliCommandRequest } from '../arguments.types.ts';
+ */
+
+import process from 'node:process';
+
+import { loadProjectGraph } from '../../graph/load-project-graph.js';
+import { inspectReverseReferences } from '../../graph/inspect-reverse-references.js';
+import { writeCommandOutput } from '../../output/command-output.js';
+import { createDerivedSummaryEvaluator } from '../../output/derived-summary.js';
+import { createRefsOutputView } from '../../output/render-output-view.js';
+
+import { renderInvalidWhereDiagnostic } from '../render-help.js';
+import { writeDiagnostics } from '../command-helpers.js';
+
+/**
+ * @param {ParsedCliCommandRequest} parsed_command
+ * @param {{ stderr: { write(chunk: string): boolean }, stdout: { isTTY?: boolean, write(chunk: string): boolean }, write_paged_output?: (output_text: string) => Promise<void> }} io_context
+ * @returns {Promise<number>}
+ */
+export async function runRefsCommand(parsed_command, io_context) {
+  const project_graph_result = await loadProjectGraph(process.cwd());
+
+  if (project_graph_result.diagnostics.length > 0) {
+    writeDiagnostics(io_context.stderr, project_graph_result.diagnostics);
+
+    return 1;
+  }
+
+  const refs_output = inspectReverseReferences(
+    project_graph_result.graph,
+    parsed_command.command_arguments[0],
+    project_graph_result.config,
+    resolveRefsWhereClause(parsed_command.command_arguments),
+  );
+
+  if (refs_output.diagnostics.length > 0) {
+    io_context.stderr.write(
+      renderInvalidWhereDiagnostic(refs_output.diagnostics[0]),
+    );
+
+    return 1;
+  }
+
+  const derived_summary_evaluator = createDerivedSummaryEvaluator(
+    project_graph_result.config,
+    project_graph_result.graph,
+  );
+
+  await writeCommandOutput(
+    io_context,
+    parsed_command,
+    createRefsOutputView(refs_output, {
+      derived_summary_evaluator,
+      repo_config: project_graph_result.config,
+    }),
+  );
+
+  return 0;
+}
+
+/**
+ * @param {string[]} command_arguments
+ * @returns {string | undefined}
+ */
+function resolveRefsWhereClause(command_arguments) {
+  if (command_arguments[1] !== '--where') {
+    return undefined;
+  }
+
+  return command_arguments.slice(2).join(' ').trim();
+}

package/lib/cli/commands/show.js

@@ -0,0 +1,58 @@
+/**
+ * @import { ParsedCliCommandRequest } from '../arguments.types.ts';
+ */
+
+import process from 'node:process';
+
+import { loadProjectGraph } from '../../graph/load-project-graph.js';
+import { writeCommandOutput } from '../../output/command-output.js';
+import { createDerivedSummaryEvaluator } from '../../output/derived-summary.js';
+import { createShowOutputView } from '../../output/render-output-view.js';
+import { loadShowOutput } from '../../output/show-document.js';
+
+import { writeDiagnostics } from '../command-helpers.js';
+
+/**
+ * @param {ParsedCliCommandRequest} parsed_command
+ * @param {{ stderr: { write(chunk: string): boolean }, stdout: { isTTY?: boolean, write(chunk: string): boolean }, write_paged_output?: (output_text: string) => Promise<void> }} io_context
+ * @returns {Promise<number>}
+ */
+export async function runShowCommand(parsed_command, io_context) {
+  const project_graph_result = await loadProjectGraph(process.cwd());
+
+  if (project_graph_result.diagnostics.length > 0) {
+    writeDiagnostics(io_context.stderr, project_graph_result.diagnostics);
+
+    return 1;
+  }
+
+  const show_output = await loadShowOutput(
+    parsed_command.command_arguments[0],
+    process.cwd(),
+    project_graph_result.graph,
+  );
+
+  if (!show_output.success) {
+    writeDiagnostics(io_context.stderr, [show_output.diagnostic]);
+
+    return 1;
+  }
+
+  const derived_summary_evaluator = createDerivedSummaryEvaluator(
+    project_graph_result.config,
+    project_graph_result.graph,
+  );
+
+  await writeCommandOutput(
+    io_context,
+    parsed_command,
+    createShowOutputView(show_output.value, {
+      derived_summary_evaluator,
+      document_node_ids: project_graph_result.graph.document_node_ids,
+      graph_nodes: project_graph_result.graph.nodes,
+      repo_config: project_graph_result.config,
+    }),
+  );
+
+  return 0;
+}

package/lib/{cli-help-metadata.js → cli/help-metadata.js}

@@ -3,7 +3,7 @@
  * @import {
  *   CliCommandName,
  *   CliHelpTopicName,
- * } from './parse-cli-arguments.types.ts';
+ * } from './arguments.types.ts';
  */
 
 /**
@@ -45,7 +45,7 @@
  * }} CliHelpTopicDefinition
  */
 
-export const COMMAND_NAMES = /** @type {const} */ ([
+const COMMAND_NAMES = /** @type {const} */ ([
   'check',
   'fields',
   'query',
@@ -54,7 +54,7 @@ export const COMMAND_NAMES = /** @type {const} */ ([
   'show',
 ]);
 
-export const HELP_TOPIC_NAMES = /** @type {const} */ (['query-language']);
+const HELP_TOPIC_NAMES = /** @type {const} */ (['query-language']);
 
 export const GLOBAL_OPTION_NAMES = new Set([
   'help',
@@ -284,14 +284,14 @@ const COMMAND_DEFINITIONS = {
   },
   show: {
     allowed_option_names: new Set(),
-    examples: ['patram show docs/patram.md', 'patram show lib/patram-cli.js'],
+    examples: ['patram show docs/patram.md', 'patram show lib/cli/main.js'],
     extra_positionals_message: 'Show accepts exactly one file path.',
     help_topics: [],
     max_positionals: 1,
     min_positionals: 1,
     missing_argument_examples: [
       'patram show docs/patram.md',
-      'patram show lib/patram-cli.js',
+      'patram show lib/cli/main.js',
     ],
     missing_argument_label: '<file>',
     missing_usage_lines: ['patram show <file>'],
@@ -583,7 +583,7 @@ function scoreCandidate(input_text, candidate) {
 function calculateDamerauLevenshteinDistance(left_text, right_text) {
   /** @type {number[][]} */
   const matrix = Array.from({ length: left_text.length + 1 }, () =>
-    Array(right_text.length + 1).fill(0),
+    Array.from({ length: right_text.length + 1 }, () => 0),
   );
 
   for (let left_index = 0; left_index <= left_text.length; left_index += 1) {