patram 0.0.2 → 0.1.1

package/lib/patram-cli.js

@@ -0,0 +1,337 @@
+/* eslint-disable max-lines */
+/**
+ * @import { ParsedCliArguments } from './parse-cli-arguments.types.ts';
+ */
+
+import process from 'node:process';
+
+import { checkGraph } from './check-graph.js';
+import {
+  shouldPageCommandOutput,
+  writeCommandOutput,
+} from './command-output.js';
+import { listRepoFiles } from './list-source-files.js';
+import { listQueries } from './list-queries.js';
+import { loadPatramConfig } from './load-patram-config.js';
+import { loadProjectGraph } from './load-project-graph.js';
+import { parseCliArguments } from './parse-cli-arguments.js';
+import { DEFAULT_QUERY_LIMIT, queryGraph } from './query-graph.js';
+import {
+  renderCheckDiagnostics,
+  renderCheckSuccess,
+} from './render-check-output.js';
+import {
+  resolveCheckTarget,
+  selectCheckTargetDiagnostics,
+  selectCheckTargetSourceFiles,
+} from './resolve-check-target.js';
+import {
+  createOutputView,
+  createShowOutputView,
+} from './render-output-view.js';
+import { resolveWhereClause } from './resolve-where-clause.js';
+import { resolveOutputMode } from './resolve-output-mode.js';
+import { loadShowOutput } from './show-document.js';
+
+/**
+ * Patram command execution flow.
+ *
+ * Loads repo state and routes `check`, `query`, `queries`, and `show` through
+ * the shared output pipeline.
+ *
+ * Kind: cli
+ * Status: active
+ * Implements Command: ../docs/reference/commands/check.md
+ * Implements Command: ../docs/reference/commands/query.md
+ * Implements Command: ../docs/reference/commands/queries.md
+ * Implements Command: ../docs/reference/commands/show.md
+ * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../docs/decisions/cli-output-architecture.md
+ * Decided by: ../docs/decisions/cli-argument-parser.md
+ * @patram
+ * @see {@link ./parse-cli-arguments.js}
+ * @see {@link ./render-output-view.js}
+ */
+
+/**
+ * Run the Patram CLI.
+ *
+ * @param {string[]} cli_arguments
+ * @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 main(cli_arguments, io_context) {
+  const parsed_arguments = parseCliArguments(cli_arguments);
+
+  if (!parsed_arguments.success) {
+    io_context.stderr.write(`${parsed_arguments.message}\n`);
+
+    return 1;
+  }
+
+  const parsed_command = parsed_arguments.value;
+
+  if (parsed_command.command_name === 'check') {
+    return runCheckCommand(parsed_command, io_context);
+  }
+
+  if (parsed_command.command_name === 'query') {
+    return runQueryCommand(parsed_command, io_context);
+  }
+
+  if (parsed_command.command_name === 'queries') {
+    return runQueriesCommand(parsed_command, io_context);
+  }
+
+  if (parsed_command.command_name === 'show') {
+    return runShowCommand(parsed_command, io_context);
+  }
+
+  io_context.stderr.write('Unknown command.\n');
+
+  return 1;
+}
+
+/**
+ * @param {ParsedCliArguments} 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>}
+ */
+async function runCheckCommand(parsed_command, io_context) {
+  const output_mode = resolveOutputMode(parsed_command, {
+    is_tty: io_context.stdout.isTTY === true,
+    no_color: process.env.NO_COLOR !== undefined,
+    term: process.env.TERM,
+  });
+  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);
+  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;
+}
+
+/**
+ * @param {ParsedCliArguments} 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>}
+ */
+async function runQueryCommand(parsed_command, io_context) {
+  const use_pager = shouldPageCommandOutput(parsed_command, io_context.stdout);
+  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,
+    createQueryPaginationOptions(parsed_command, use_pager),
+  );
+
+  if (query_result.diagnostics.length > 0) {
+    writeDiagnostics(io_context.stderr, query_result.diagnostics);
+
+    return 1;
+  }
+
+  await writeCommandOutput(
+    io_context,
+    parsed_command,
+    createOutputView(
+      'query',
+      query_result.nodes,
+      createQueryOutputOptions(parsed_command, query_result, use_pager),
+    ),
+  );
+
+  return 0;
+}
+
+/**
+ * @param {ParsedCliArguments} 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>}
+ */
+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;
+}
+
+/**
+ * @param {ParsedCliArguments} 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>}
+ */
+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;
+  }
+
+  await writeCommandOutput(
+    io_context,
+    parsed_command,
+    createShowOutputView(show_output.value),
+  );
+
+  return 0;
+}
+
+/**
+ * @param {{ write(chunk: string): boolean }} output_stream
+ * @param {import('./load-patram-config.types.ts').PatramDiagnostic[]} diagnostics
+ */
+function writeDiagnostics(output_stream, diagnostics) {
+  for (const diagnostic of diagnostics) {
+    output_stream.write(formatDiagnostic(diagnostic));
+  }
+}
+
+/**
+ * @param {ParsedCliArguments} parsed_command
+ * @param {{ total_count: number, nodes: import('./build-graph.types.ts').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 "kind=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 {ParsedCliArguments} 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 {import('./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/patram-config.js

@@ -8,7 +8,8 @@ import { z } from 'zod';
 const KIND_NAME_SCHEMA = z.string().min(1);
 const RELATION_NAME_SCHEMA = z.string().min(1);
 const CLAIM_TYPE_SCHEMA = z.string().min(1);
-const TARGET_SCHEMA = z.enum(['path']);
+const KEY_SOURCE_SCHEMA = z.enum(['path', 'value']);
+const TARGET_SCHEMA = z.enum(['path', 'value']);
 
 const kind_definition_schema = z
   .object({
@@ -28,6 +29,7 @@ const relation_definition_schema = z
 const mapping_node_schema = z
   .object({
     field: z.string().min(1),
+    key: KEY_SOURCE_SCHEMA.optional(),
     kind: KIND_NAME_SCHEMA,
   })
   .strict();

package/lib/patram-config.types.ts

@@ -11,12 +11,13 @@ export interface RelationDefinition {
 
 export interface MappingNodeDefinition {
   field: string;
+  key?: 'path' | 'value';
   kind: string;
 }
 
 export interface MappingEmitDefinition {
   relation: string;
-  target: 'path';
+  target: 'path' | 'value';
   target_kind: string;
 }
 

package/lib/query-graph.js

@@ -0,0 +1,256 @@
+/**
+ * @import { BuildGraphResult, GraphNode } from './build-graph.types.ts';
+ * @import { PatramDiagnostic } from './load-patram-config.types.ts';
+ */
+
+import { parseWhereClause } from './parse-where-clause.js';
+
+/**
+ * Query graph filtering.
+ *
+ * Applies the v0 where-clause language to graph nodes and keeps pagination
+ * separate from matching.
+ *
+ * Kind: graph
+ * Status: active
+ * Uses Term: ../docs/reference/terms/graph.md
+ * Uses Term: ../docs/reference/terms/query.md
+ * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../docs/decisions/query-language.md
+ * Implements: ../docs/tasks/v0/query-command.md
+ * @patram
+ * @see {@link ./load-project-graph.js}
+ * @see {@link ../docs/decisions/query-language.md}
+ */
+
+export const DEFAULT_QUERY_LIMIT = 25;
+
+/**
+ * Filter graph nodes with the v0 query language.
+ *
+ * @param {BuildGraphResult} graph
+ * @param {string} where_clause
+ * @param {{ limit?: number, offset?: number }=} pagination_options
+ * @returns {{ diagnostics: PatramDiagnostic[], nodes: GraphNode[], total_count: number }}
+ */
+export function queryGraph(graph, where_clause, pagination_options = {}) {
+  const parse_result = parseWhereClause(where_clause);
+
+  if (!parse_result.success) {
+    return {
+      diagnostics: [parse_result.diagnostic],
+      nodes: [],
+      total_count: 0,
+    };
+  }
+
+  const predicates = parse_result.clauses.map(createPredicate);
+  const relation_index = createRelationIndex(graph.edges);
+  const graph_nodes = Object.values(graph.nodes).sort(compareGraphNodes);
+  const matching_nodes = graph_nodes.filter((graph_node) =>
+    predicates.every((predicate) => predicate(graph_node, relation_index)),
+  );
+  const paginated_nodes = paginateNodes(matching_nodes, pagination_options);
+
+  return {
+    diagnostics: [],
+    nodes: paginated_nodes,
+    total_count: matching_nodes.length,
+  };
+}
+
+/**
+ * @param {{ is_negated: boolean, term: { kind: 'field', field_name: 'id' | 'kind' | 'path' | 'status' | 'title', operator: '=' | '^=' | '~', value: string } | { kind: 'relation', relation_name: string } | { kind: 'relation_target', relation_name: string, target_id: string } }} clause
+ * @returns {(graph_node: GraphNode, relation_index: Map<string, Map<string, Set<string>>>) => boolean}
+ */
+function createPredicate(clause) {
+  if (clause.term.kind === 'relation') {
+    return createRelationPredicate(
+      clause.term.relation_name,
+      clause.is_negated,
+    );
+  }
+
+  if (clause.term.kind === 'relation_target') {
+    return createRelationTargetPredicate(
+      clause.term.relation_name,
+      clause.term.target_id,
+      clause.is_negated,
+    );
+  }
+
+  return createFieldPredicateFromTerm(clause.term, clause.is_negated);
+}
+
+/**
+ * @param {string} relation_name
+ * @param {boolean} is_negated
+ * @returns {(graph_node: GraphNode, relation_index: Map<string, Map<string, Set<string>>>) => boolean}
+ */
+function createRelationPredicate(relation_name, is_negated) {
+  return (graph_node, relation_index) => {
+    const relation_targets = relation_index.get(graph_node.id);
+    const is_match = relation_targets?.has(relation_name) ?? false;
+
+    return is_negated ? !is_match : is_match;
+  };
+}
+
+/**
+ * @param {string} relation_name
+ * @param {string} target_id
+ * @param {boolean} is_negated
+ * @returns {(graph_node: GraphNode, relation_index: Map<string, Map<string, Set<string>>>) => boolean}
+ */
+function createRelationTargetPredicate(relation_name, target_id, is_negated) {
+  return (graph_node, relation_index) => {
+    const relation_targets = relation_index.get(graph_node.id);
+    const matching_targets = relation_targets?.get(relation_name);
+    const is_match = matching_targets?.has(target_id) ?? false;
+
+    return is_negated ? !is_match : is_match;
+  };
+}
+
+/**
+ * @param {BuildGraphResult['edges']} graph_edges
+ * @returns {Map<string, Map<string, Set<string>>>}
+ */
+function createRelationIndex(graph_edges) {
+  /** @type {Map<string, Map<string, Set<string>>>} */
+  const relation_index = new Map();
+
+  for (const graph_edge of graph_edges) {
+    let relation_targets = relation_index.get(graph_edge.from);
+
+    if (!relation_targets) {
+      relation_targets = new Map();
+      relation_index.set(graph_edge.from, relation_targets);
+    }
+
+    let target_ids = relation_targets.get(graph_edge.relation);
+
+    if (!target_ids) {
+      target_ids = new Set();
+      relation_targets.set(graph_edge.relation, target_ids);
+    }
+
+    target_ids.add(graph_edge.to);
+  }
+
+  return relation_index;
+}
+
+/**
+ * @param {string} field_name
+ * @param {string} expected_value
+ * @param {boolean} is_negated
+ * @returns {(graph_node: GraphNode) => boolean}
+ */
+function createFieldPredicate(field_name, expected_value, is_negated) {
+  return (graph_node) => {
+    const actual_value = graph_node[field_name];
+    const is_match = actual_value === expected_value;
+
+    return is_negated ? !is_match : is_match;
+  };
+}
+
+/**
+ * @param {string} id_prefix
+ * @param {boolean} is_negated
+ * @returns {(graph_node: GraphNode) => boolean}
+ */
+function createIdPrefixPredicate(id_prefix, is_negated) {
+  return (graph_node) => {
+    const id_value = graph_node.id;
+    const is_match = id_value.startsWith(id_prefix);
+
+    return is_negated ? !is_match : is_match;
+  };
+}
+
+/**
+ * @param {string} path_prefix
+ * @param {boolean} is_negated
+ * @returns {(graph_node: GraphNode) => boolean}
+ */
+function createPathPrefixPredicate(path_prefix, is_negated) {
+  return (graph_node) => {
+    const path_value = graph_node.path ?? '';
+    const is_match = path_value.startsWith(path_prefix);
+
+    return is_negated ? !is_match : is_match;
+  };
+}
+
+/**
+ * @param {string} title_text
+ * @param {boolean} is_negated
+ * @returns {(graph_node: GraphNode) => boolean}
+ */
+function createTitlePredicate(title_text, is_negated) {
+  const normalized_title_text = title_text.toLocaleLowerCase('en');
+
+  return (graph_node) => {
+    const title_value = graph_node.title ?? '';
+    const is_match = title_value
+      .toLocaleLowerCase('en')
+      .includes(normalized_title_text);
+
+    return is_negated ? !is_match : is_match;
+  };
+}
+
+/**
+ * @param {{ field_name: 'id' | 'kind' | 'path' | 'status' | 'title', kind: 'field', operator: '=' | '^=' | '~', value: string }} term
+ * @param {boolean} is_negated
+ * @returns {(graph_node: GraphNode, relation_index: Map<string, Map<string, Set<string>>>) => boolean}
+ */
+function createFieldPredicateFromTerm(term, is_negated) {
+  const term_key = `${term.field_name}${term.operator}`;
+
+  if (
+    term_key === 'id=' ||
+    term_key === 'kind=' ||
+    term_key === 'status=' ||
+    term_key === 'path='
+  ) {
+    return createFieldPredicate(term.field_name, term.value, is_negated);
+  }
+
+  if (term_key === 'id^=') {
+    return createIdPrefixPredicate(term.value, is_negated);
+  }
+
+  if (term_key === 'path^=') {
+    return createPathPrefixPredicate(term.value, is_negated);
+  }
+
+  if (term_key === 'title~') {
+    return createTitlePredicate(term.value, is_negated);
+  }
+
+  throw new Error('Unsupported parsed where clause.');
+}
+
+/**
+ * @param {GraphNode} left_node
+ * @param {GraphNode} right_node
+ * @returns {number}
+ */
+function compareGraphNodes(left_node, right_node) {
+  return left_node.id.localeCompare(right_node.id, 'en');
+}
+
+/**
+ * @param {GraphNode[]} matching_nodes
+ * @param {{ limit?: number, offset?: number }} pagination_options
+ * @returns {GraphNode[]}
+ */
+function paginateNodes(matching_nodes, pagination_options) {
+  const offset = pagination_options.offset ?? 0;
+  const limit = pagination_options.limit ?? matching_nodes.length;
+
+  return matching_nodes.slice(offset, offset + limit);
+}