patram 0.1.1 → 0.3.0

package/lib/parse-where-clause.types.ts

@@ -0,0 +1,72 @@
+import type { PatramDiagnostic } from './load-patram-config.types.ts';
+
+export type ParsedFieldName = string;
+
+export interface ParsedFieldTerm {
+  column: number;
+  field_name: ParsedFieldName;
+  kind: 'field';
+  operator: '!=' | '<' | '<=' | '=' | '>' | '>=' | '^=' | '~';
+  value: string;
+}
+
+export interface ParsedFieldSetTerm {
+  column: number;
+  field_name: ParsedFieldName;
+  kind: 'field_set';
+  operator: 'in' | 'not in';
+  values: string[];
+}
+
+export interface ParsedTraversalTerm {
+  column: number;
+  direction: 'in' | 'out';
+  relation_name: string;
+}
+
+export interface ParsedRelationTerm {
+  column: number;
+  kind: 'relation';
+  relation_name: string;
+}
+
+export interface ParsedRelationTargetTerm {
+  column: number;
+  kind: 'relation_target';
+  relation_name: string;
+  target_id: string;
+}
+
+export type ParsedAggregateComparison = '!=' | '<' | '<=' | '=' | '>' | '>=';
+export type ParsedAggregateName = 'any' | 'count' | 'none';
+
+export interface ParsedAggregateTerm {
+  aggregate_name: ParsedAggregateName;
+  clauses: ParsedClause[];
+  comparison?: ParsedAggregateComparison;
+  kind: 'aggregate';
+  traversal: ParsedTraversalTerm;
+  value?: number;
+}
+
+export type ParsedTerm =
+  | ParsedAggregateTerm
+  | ParsedFieldSetTerm
+  | ParsedFieldTerm
+  | ParsedRelationTargetTerm
+  | ParsedRelationTerm;
+
+export interface ParsedClause {
+  is_negated: boolean;
+  term: ParsedTerm;
+}
+
+export type ParseWhereClauseResult =
+  | {
+      clauses: ParsedClause[];
+      success: true;
+    }
+  | {
+      diagnostic: PatramDiagnostic;
+      success: false;
+    };

package/lib/patram-cli.js

@@ -1,6 +1,6 @@
 /* eslint-disable max-lines */
 /**
- * @import { ParsedCliArguments } from './parse-cli-arguments.types.ts';
+ * @import { ParsedCliCommandRequest } from './parse-cli-arguments.types.ts';
  */
 
 import process from 'node:process';
@@ -10,16 +10,24 @@ import {
   shouldPageCommandOutput,
   writeCommandOutput,
 } from './command-output.js';
+import { discoverFields } from './discover-fields.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 { inspectQuery, renderQueryInspection } from './query-inspection.js';
+import { createDerivedSummaryEvaluator } from './derived-summary.js';
 import {
   renderCheckDiagnostics,
   renderCheckSuccess,
 } from './render-check-output.js';
+import {
+  renderCliParseError,
+  renderHelpRequest,
+  renderInvalidWhereDiagnostic,
+} from './render-cli-help.js';
 import {
   resolveCheckTarget,
   selectCheckTargetDiagnostics,
@@ -29,6 +37,7 @@ import {
   createOutputView,
   createShowOutputView,
 } from './render-output-view.js';
+import { renderFieldDiscovery } from './render-field-discovery.js';
 import { resolveWhereClause } from './resolve-where-clause.js';
 import { resolveOutputMode } from './resolve-output-mode.js';
 import { loadShowOutput } from './show-document.js';
@@ -36,8 +45,8 @@ 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.
+ * Loads repo state and routes `check`, `fields`, `query`, `queries`, and
+ * `show` through the shared output pipeline.
  *
  * Kind: cli
  * Status: active
@@ -64,12 +73,20 @@ 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`);
+    io_context.stderr.write(renderCliParseError(parsed_arguments.error));
 
     return 1;
   }
 
-  const parsed_command = parsed_arguments.value;
+  if (parsed_arguments.value.kind === 'help') {
+    io_context.stdout.write(renderHelpRequest(parsed_arguments.value));
+
+    return 0;
+  }
+
+  const parsed_command = /** @type {ParsedCliCommandRequest} */ (
+    parsed_arguments.value
+  );
 
   if (parsed_command.command_name === 'check') {
     return runCheckCommand(parsed_command, io_context);
@@ -79,6 +96,10 @@ export async function main(cli_arguments, io_context) {
     return runQueryCommand(parsed_command, io_context);
   }
 
+  if (parsed_command.command_name === 'fields') {
+    return runFieldsCommand(parsed_command, io_context);
+  }
+
   if (parsed_command.command_name === 'queries') {
     return runQueriesCommand(parsed_command, io_context);
   }
@@ -93,7 +114,7 @@ export async function main(cli_arguments, io_context) {
 }
 
 /**
- * @param {ParsedCliArguments} parsed_command
+ * @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>}
  */
@@ -125,7 +146,12 @@ async function runCheckCommand(parsed_command, io_context) {
     return 1;
   }
 
-  const diagnostics = checkGraph(project_graph_result.graph, repo_file_paths);
+  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,
@@ -147,12 +173,27 @@ async function runCheckCommand(parsed_command, io_context) {
 }
 
 /**
- * @param {ParsedCliArguments} parsed_command
+ * @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>}
  */
 async function runQueryCommand(parsed_command, io_context) {
   const use_pager = shouldPageCommandOutput(parsed_command, io_context.stdout);
+  const output_mode = resolveOutputMode(parsed_command, {
+    is_tty: io_context.stdout.isTTY === true,
+    no_color: process.env.NO_COLOR !== undefined,
+    term: process.env.TERM,
+  });
+
+  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) {
@@ -174,31 +215,123 @@ async function runQueryCommand(parsed_command, io_context) {
 
   const query_result = queryGraph(
     project_graph_result.graph,
-    where_clause.value,
+    where_clause.value.where_clause,
+    project_graph_result.config,
     createQueryPaginationOptions(parsed_command, use_pager),
   );
 
   if (query_result.diagnostics.length > 0) {
-    writeDiagnostics(io_context.stderr, query_result.diagnostics);
+    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,
-      createQueryOutputOptions(parsed_command, query_result, use_pager),
-    ),
+    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
+ * @returns {Promise<number>}
+ */
+async function runFieldsCommand(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 discovery_result = await discoverFields(process.cwd());
+
+  io_context.stdout.write(renderFieldDiscovery(discovery_result, output_mode));
+
+  return 0;
+}
+
+/**
+ * @param {ParsedCliCommandRequest} parsed_command
+ * @param {{ stderr: { write(chunk: string): boolean }, stdout: { isTTY?: boolean, write(chunk: string): boolean } }} io_context
+ * @param {import('./output-view.types.ts').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 {ParsedCliArguments} parsed_command
+ * @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>}
  */
@@ -227,7 +360,7 @@ async function runQueriesCommand(parsed_command, io_context) {
 }
 
 /**
- * @param {ParsedCliArguments} parsed_command
+ * @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>}
  */
@@ -252,10 +385,19 @@ async function runShowCommand(parsed_command, io_context) {
     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),
+    createShowOutputView(show_output.value, {
+      derived_summary_evaluator,
+      graph_nodes: project_graph_result.graph.nodes,
+      repo_config: project_graph_result.config,
+    }),
   );
 
   return 0;
@@ -272,7 +414,7 @@ function writeDiagnostics(output_stream, diagnostics) {
 }
 
 /**
- * @param {ParsedCliArguments} parsed_command
+ * @param {ParsedCliCommandRequest} 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 }}
@@ -286,7 +428,7 @@ function createQueryOutputOptions(parsed_command, query_result, use_pager) {
   const offset = parsed_command.query_offset ?? 0;
 
   if (query_result.total_count === 0) {
-    hints.push('Try: patram query --where "kind=task"');
+    hints.push('Try: patram query --where "$class=task"');
   }
 
   if (
@@ -309,7 +451,7 @@ function createQueryOutputOptions(parsed_command, query_result, use_pager) {
 }
 
 /**
- * @param {ParsedCliArguments} parsed_command
+ * @param {ParsedCliCommandRequest} parsed_command
  * @param {boolean} use_pager
  * @returns {{ limit?: number, offset: number }}
  */
@@ -328,6 +470,23 @@ function createQueryPaginationOptions(parsed_command, use_pager) {
   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,
+  };
+}
+
 /**
  * @param {import('./load-patram-config.types.ts').PatramDiagnostic} diagnostic
  * @returns {string}

package/lib/patram-config.js

@@ -5,13 +5,13 @@
 
 import { z } from 'zod';
 
-const KIND_NAME_SCHEMA = z.string().min(1);
+const CLASS_NAME_SCHEMA = z.string().min(1);
 const RELATION_NAME_SCHEMA = z.string().min(1);
 const CLAIM_TYPE_SCHEMA = z.string().min(1);
 const KEY_SOURCE_SCHEMA = z.enum(['path', 'value']);
 const TARGET_SCHEMA = z.enum(['path', 'value']);
 
-const kind_definition_schema = z
+const class_definition_schema = z
   .object({
     builtin: z.boolean().optional(),
     label: z.string().min(1).optional(),
@@ -21,16 +21,16 @@ const kind_definition_schema = z
 const relation_definition_schema = z
   .object({
     builtin: z.boolean().optional(),
-    from: z.array(KIND_NAME_SCHEMA).min(1),
-    to: z.array(KIND_NAME_SCHEMA).min(1),
+    from: z.array(CLASS_NAME_SCHEMA).min(1),
+    to: z.array(CLASS_NAME_SCHEMA).min(1),
   })
   .strict();
 
 const mapping_node_schema = z
   .object({
+    class: CLASS_NAME_SCHEMA,
     field: z.string().min(1),
     key: KEY_SOURCE_SCHEMA.optional(),
-    kind: KIND_NAME_SCHEMA,
   })
   .strict();
 
@@ -38,7 +38,7 @@ const mapping_emit_schema = z
   .object({
     relation: RELATION_NAME_SCHEMA,
     target: TARGET_SCHEMA,
-    target_kind: KIND_NAME_SCHEMA,
+    target_class: CLASS_NAME_SCHEMA,
   })
   .strict();
 
@@ -53,7 +53,7 @@ const mapping_definition_schema = z
 export const patramConfigSchema = z
   .object({
     $schema: z.url().optional(),
-    kinds: z.record(KIND_NAME_SCHEMA, kind_definition_schema),
+    classes: z.record(CLASS_NAME_SCHEMA, class_definition_schema),
     mappings: z.record(CLAIM_TYPE_SCHEMA, mapping_definition_schema),
     relations: z.record(RELATION_NAME_SCHEMA, relation_definition_schema),
   })
@@ -90,8 +90,8 @@ function validateMappingDefinition(mapping_definition, refinement_context) {
  * @param {RefinementCtx} refinement_context
  */
 function validatePatramConfigReferences(config_json, refinement_context) {
-  validateRelationKinds(config_json, refinement_context);
-  validateMappingKinds(config_json, refinement_context);
+  validateRelationClasses(config_json, refinement_context);
+  validateMappingClasses(config_json, refinement_context);
   validateMappingRelations(config_json, refinement_context);
 }
 
@@ -99,19 +99,19 @@ function validatePatramConfigReferences(config_json, refinement_context) {
  * @param {PatramConfig} config_json
  * @param {RefinementCtx} refinement_context
  */
-function validateRelationKinds(config_json, refinement_context) {
+function validateRelationClasses(config_json, refinement_context) {
   for (const [relation_name, relation_definition] of Object.entries(
     config_json.relations,
   )) {
-    validateReferencedKinds(
+    validateReferencedClasses(
       relation_definition.from,
-      config_json.kinds,
+      config_json.classes,
       ['relations', relation_name, 'from'],
       refinement_context,
     );
-    validateReferencedKinds(
+    validateReferencedClasses(
       relation_definition.to,
-      config_json.kinds,
+      config_json.classes,
       ['relations', relation_name, 'to'],
       refinement_context,
     );
@@ -122,24 +122,24 @@ function validateRelationKinds(config_json, refinement_context) {
  * @param {PatramConfig} config_json
  * @param {RefinementCtx} refinement_context
  */
-function validateMappingKinds(config_json, refinement_context) {
+function validateMappingClasses(config_json, refinement_context) {
   for (const [mapping_name, mapping_definition] of Object.entries(
     config_json.mappings,
   )) {
     if (mapping_definition.emit) {
-      validateReferencedKinds(
-        [mapping_definition.emit.target_kind],
-        config_json.kinds,
-        ['mappings', mapping_name, 'emit', 'target_kind'],
+      validateReferencedClasses(
+        [mapping_definition.emit.target_class],
+        config_json.classes,
+        ['mappings', mapping_name, 'emit', 'target_class'],
         refinement_context,
       );
     }
 
     if (mapping_definition.node) {
-      validateReferencedKinds(
-        [mapping_definition.node.kind],
-        config_json.kinds,
-        ['mappings', mapping_name, 'node', 'kind'],
+      validateReferencedClasses(
+        [mapping_definition.node.class],
+        config_json.classes,
+        ['mappings', mapping_name, 'node', 'class'],
         refinement_context,
       );
     }
@@ -171,25 +171,25 @@ function validateMappingRelations(config_json, refinement_context) {
 }
 
 /**
- * @param {string[]} referenced_kinds
- * @param {Record<string, unknown>} known_kinds
+ * @param {string[]} referenced_classes
+ * @param {Record<string, unknown>} known_classes
  * @param {(string | number)[]} issue_path
  * @param {RefinementCtx} refinement_context
  */
-function validateReferencedKinds(
-  referenced_kinds,
-  known_kinds,
+function validateReferencedClasses(
+  referenced_classes,
+  known_classes,
   issue_path,
   refinement_context,
 ) {
-  for (const referenced_kind of referenced_kinds) {
-    if (known_kinds[referenced_kind]) {
+  for (const referenced_class of referenced_classes) {
+    if (known_classes[referenced_class]) {
       continue;
     }
 
     refinement_context.addIssue({
       code: 'custom',
-      message: `Unknown kind "${referenced_kind}".`,
+      message: `Unknown class "${referenced_class}".`,
       path: issue_path,
     });
   }

package/lib/patram-config.types.ts

@@ -1,4 +1,4 @@
-export interface KindDefinition {
+export interface ClassDefinition {
   builtin?: boolean;
   label?: string;
 }
@@ -10,15 +10,15 @@ export interface RelationDefinition {
 }
 
 export interface MappingNodeDefinition {
+  class: string;
   field: string;
   key?: 'path' | 'value';
-  kind: string;
 }
 
 export interface MappingEmitDefinition {
   relation: string;
   target: 'path' | 'value';
-  target_kind: string;
+  target_class: string;
 }
 
 export interface MappingDefinition {
@@ -28,7 +28,13 @@ export interface MappingDefinition {
 
 export interface PatramConfig {
   $schema?: string;
-  kinds: Record<string, KindDefinition>;
+  classes: Record<string, ClassDefinition>;
+  class_schemas?: Record<string, ClassSchemaConfig>;
+  fields?: Record<string, MetadataFieldConfig>;
   mappings: Record<string, MappingDefinition>;
   relations: Record<string, RelationDefinition>;
 }
+import type {
+  ClassSchemaConfig,
+  MetadataFieldConfig,
+} from './load-patram-config.types.ts';

package/lib/patram.js

@@ -0,0 +1,6 @@
+export {
+  extractTaggedFencedBlocks,
+  loadTaggedFencedBlocks,
+  selectTaggedBlock,
+  selectTaggedBlocks,
+} from './tagged-fenced-blocks.js';