patram 0.2.0 → 0.4.0

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

@@ -1,15 +1,17 @@
 import type { PatramDiagnostic } from './load-patram-config.types.ts';
 
-export type ParsedFieldName = 'id' | 'kind' | 'path' | 'status' | 'title';
+export type ParsedFieldName = string;
 
 export interface ParsedFieldTerm {
+  column: number;
   field_name: ParsedFieldName;
   kind: 'field';
-  operator: '=' | '^=' | '~';
+  operator: '!=' | '<' | '<=' | '=' | '>' | '>=' | '^=' | '~';
   value: string;
 }
 
 export interface ParsedFieldSetTerm {
+  column: number;
   field_name: ParsedFieldName;
   kind: 'field_set';
   operator: 'in' | 'not in';
@@ -40,13 +42,28 @@ export type ParsedAggregateName = 'any' | 'count' | 'none';
 
 export interface ParsedAggregateTerm {
   aggregate_name: ParsedAggregateName;
-  clauses: ParsedClause[];
   comparison?: ParsedAggregateComparison;
+  expression: ParsedExpression;
   kind: 'aggregate';
   traversal: ParsedTraversalTerm;
   value?: number;
 }
 
+export interface ParsedTermExpression {
+  kind: 'term';
+  term: ParsedTerm;
+}
+
+export interface ParsedNotExpression {
+  expression: ParsedExpression;
+  kind: 'not';
+}
+
+export interface ParsedBooleanExpression {
+  expressions: ParsedExpression[];
+  kind: 'and' | 'or';
+}
+
 export type ParsedTerm =
   | ParsedAggregateTerm
   | ParsedFieldSetTerm
@@ -54,14 +71,14 @@ export type ParsedTerm =
   | ParsedRelationTargetTerm
   | ParsedRelationTerm;
 
-export interface ParsedClause {
-  is_negated: boolean;
-  term: ParsedTerm;
-}
+export type ParsedExpression =
+  | ParsedBooleanExpression
+  | ParsedNotExpression
+  | ParsedTermExpression;
 
 export type ParseWhereClauseResult =
   | {
-      clauses: ParsedClause[];
+      expression: ParsedExpression;
       success: true;
     }
   | {

package/lib/patram-cli.js

@@ -9,7 +9,9 @@ import { checkGraph } from './check-graph.js';
 import {
   shouldPageCommandOutput,
   writeCommandOutput,
+  writeRenderedCommandOutput,
 } 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';
@@ -36,6 +38,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';
@@ -43,8 +46,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
@@ -94,6 +97,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);
   }
@@ -140,7 +147,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,
@@ -205,6 +217,7 @@ async function runQueryCommand(parsed_command, io_context) {
   const query_result = queryGraph(
     project_graph_result.graph,
     where_clause.value.where_clause,
+    project_graph_result.config,
     createQueryPaginationOptions(parsed_command, use_pager),
   );
 
@@ -227,12 +240,42 @@ async function runQueryCommand(parsed_command, io_context) {
     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 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 {ParsedCliCommandRequest} parsed_command
  * @param {{ stderr: { write(chunk: string): boolean }, stdout: { isTTY?: boolean, write(chunk: string): boolean } }} io_context
@@ -364,7 +407,9 @@ async function runShowCommand(parsed_command, 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,
     }),
   );
 
@@ -396,7 +441,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 (
@@ -462,3 +507,22 @@ function createQueryExecutionOptions(parsed_command, use_pager) {
 function formatDiagnostic(diagnostic) {
   return `${diagnostic.path}:${diagnostic.line}:${diagnostic.column} ${diagnostic.level} ${diagnostic.code} ${diagnostic.message}\n`;
 }
+
+/**
+ * @param {import('./load-patram-config.types.ts').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/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';