patram 0.2.0 → 0.3.0

package/lib/load-patram-config.types.ts

@@ -1,5 +1,5 @@
 import type {
-  KindDefinition,
+  ClassDefinition,
   MappingDefinition,
   RelationDefinition,
 } from './patram-config.types.ts';
@@ -8,6 +8,98 @@ export interface StoredQueryConfig {
   where: string;
 }
 
+export type FieldValueTypeName =
+  | 'string'
+  | 'integer'
+  | 'enum'
+  | 'path'
+  | 'glob'
+  | 'date'
+  | 'date_time';
+
+export interface FieldDisplayConfig {
+  hidden?: boolean;
+  order?: number;
+}
+
+export interface FieldQueryConfig {
+  contains?: boolean;
+  prefix?: boolean;
+}
+
+export interface StringFieldConfig {
+  display?: FieldDisplayConfig;
+  multiple?: boolean;
+  query?: FieldQueryConfig;
+  type: 'string';
+}
+
+export interface IntegerFieldConfig {
+  display?: FieldDisplayConfig;
+  multiple?: boolean;
+  type: 'integer';
+}
+
+export interface EnumFieldConfig {
+  display?: FieldDisplayConfig;
+  multiple?: boolean;
+  type: 'enum';
+  values: string[];
+}
+
+export interface PathFieldConfig {
+  display?: FieldDisplayConfig;
+  multiple?: boolean;
+  path_class?: string;
+  type: 'path';
+}
+
+export interface GlobFieldConfig {
+  display?: FieldDisplayConfig;
+  multiple?: boolean;
+  type: 'glob';
+}
+
+export interface DateFieldConfig {
+  display?: FieldDisplayConfig;
+  multiple?: boolean;
+  type: 'date';
+}
+
+export interface DateTimeFieldConfig {
+  display?: FieldDisplayConfig;
+  multiple?: boolean;
+  type: 'date_time';
+}
+
+export type MetadataFieldConfig =
+  | DateFieldConfig
+  | DateTimeFieldConfig
+  | EnumFieldConfig
+  | GlobFieldConfig
+  | IntegerFieldConfig
+  | PathFieldConfig
+  | StringFieldConfig;
+
+export interface ClassFieldRuleConfig {
+  presence: 'required' | 'optional' | 'forbidden';
+}
+
+export type DirectiveTypeConfig = MetadataFieldConfig;
+export type MetadataDirectiveRuleConfig = ClassFieldRuleConfig;
+
+export interface ClassSchemaConfig {
+  document_path_class?: string;
+  fields: Record<string, ClassFieldRuleConfig>;
+  unknown_fields?: 'ignore' | 'error';
+}
+
+export type MetadataSchemaConfig = ClassSchemaConfig;
+
+export interface PathClassConfig {
+  prefixes: string[];
+}
+
 export type DerivedSummaryScalar = boolean | number | string | null;
 
 export interface DerivedSummaryCountFieldConfig {
@@ -34,15 +126,18 @@ export type DerivedSummaryFieldConfig =
   | DerivedSummarySelectFieldConfig;
 
 export interface DerivedSummaryConfig {
+  classes: string[];
   fields: DerivedSummaryFieldConfig[];
-  kinds: string[];
 }
 
 export interface PatramRepoConfig {
+  class_schemas?: Record<string, ClassSchemaConfig>;
+  classes?: Record<string, ClassDefinition>;
   derived_summaries?: Record<string, DerivedSummaryConfig>;
+  fields?: Record<string, MetadataFieldConfig>;
   include: string[];
-  kinds?: Record<string, KindDefinition>;
   mappings?: Record<string, MappingDefinition>;
+  path_classes?: Record<string, PathClassConfig>;
   queries: Record<string, StoredQueryConfig>;
   relations?: Record<string, RelationDefinition>;
 }

package/lib/load-project-graph.js

@@ -36,13 +36,14 @@ import { resolvePatramGraphConfig } from './resolve-patram-graph-config.js';
  * project directory.
  *
  * @param {string} project_directory
- * @returns {Promise<{ config: PatramRepoConfig, diagnostics: PatramDiagnostic[], graph: BuildGraphResult, source_file_paths: string[] }>}
+ * @returns {Promise<{ claims: PatramClaim[], config: PatramRepoConfig, diagnostics: PatramDiagnostic[], graph: BuildGraphResult, source_file_paths: string[] }>}
  */
 export async function loadProjectGraph(project_directory) {
   const load_result = await loadPatramConfig(project_directory);
 
   if (load_result.diagnostics.length > 0) {
     return {
+      claims: [],
       config: {
         include: [],
         queries: {},
@@ -74,6 +75,7 @@ export async function loadProjectGraph(project_directory) {
 
   if (collect_result.diagnostics.length > 0) {
     return {
+      claims: collect_result.claims,
       config: repo_config,
       diagnostics: collect_result.diagnostics,
       graph: {
@@ -85,6 +87,7 @@ export async function loadProjectGraph(project_directory) {
   }
 
   return {
+    claims: collect_result.claims,
     config: repo_config,
     diagnostics: [],
     graph: buildGraph(graph_config, collect_result.claims),

package/lib/output-view.types.ts

@@ -12,6 +12,11 @@ export interface OutputDerivedSummary {
   name: string;
 }
 
+export interface OutputMetadataField {
+  name: string;
+  value: string | string[];
+}
+
 export interface OutputViewSummary {
   count: number;
   kind: 'resolved_link_list' | 'result_list' | 'stored_query_list';
@@ -26,12 +31,13 @@ export interface QueryOutputViewSummary extends OutputViewSummary {
 
 export interface OutputNodeItem {
   derived_summary?: OutputDerivedSummary;
+  fields: Record<string, string | string[]>;
   id: string;
   kind: 'node';
-  node_kind: GraphNode['kind'];
-  path: string;
-  status?: string;
+  node_kind: string;
+  path?: string;
   title: string;
+  visible_fields: OutputMetadataField[];
 }
 
 export interface OutputStoredQueryItem {
@@ -42,10 +48,12 @@ export interface OutputStoredQueryItem {
 
 export interface OutputResolvedLinkTarget {
   derived_summary?: OutputDerivedSummary;
-  kind?: string;
-  path: string;
-  status?: string;
+  fields: Record<string, string | string[]>;
+  id: string;
+  kind: string;
+  path?: string;
   title: string;
+  visible_fields: OutputMetadataField[];
 }
 
 export interface OutputResolvedLinkItem {

package/lib/parse-cli-arguments.types.ts

@@ -1,4 +1,4 @@
-export type CliCommandName = 'check' | 'query' | 'queries' | 'show';
+export type CliCommandName = 'check' | 'fields' | 'query' | 'queries' | 'show';
 export type CliHelpTopicName = 'query-language';
 export type CliHelpTargetKind = 'root' | 'command' | 'topic';
 

package/lib/parse-where-clause.js

@@ -218,10 +218,7 @@ function parseAtomicTerm(parser_state) {
     return failToken(parser_state);
   }
 
-  return (
-    parseFieldSet(parser_state, field_or_relation_name) ??
-    parseOperatorTerm(parser_state, start_index, field_or_relation_name)
-  );
+  return parseOperatorTerm(parser_state, start_index, field_or_relation_name);
 }
 
 /**
@@ -259,16 +256,12 @@ function createAggregateTerm(parser_state, aggregate_name, traversal, clauses) {
 
 /**
  * @param {ParserState} parser_state
+ * @param {number} start_index
  * @param {ParsedFieldName | string} field_name
  * @returns {ParseTermResult | null}
  */
-function parseFieldSet(parser_state, field_name) {
-  if (!isSupportedFieldName(field_name)) {
-    return null;
-  }
-
-  const start_index = parser_state.index;
-
+function parseFieldSet(parser_state, start_index, field_name) {
+  const operator_start_index = parser_state.index;
   if (!consumeRequiredWhitespace(parser_state)) {
     return null;
   }
@@ -276,7 +269,7 @@ function parseFieldSet(parser_state, field_name) {
   const operator = parseSetOperator(parser_state);
 
   if (!operator) {
-    parser_state.index = start_index;
+    parser_state.index = operator_start_index;
     return null;
   }
 
@@ -287,7 +280,13 @@ function parseFieldSet(parser_state, field_name) {
   const values = parseList(parser_state);
 
   return values
-    ? success({ field_name, kind: 'field_set', operator, values })
+    ? success({
+        column: start_index + 1,
+        field_name,
+        kind: 'field_set',
+        operator,
+        values,
+      })
     : failToken(parser_state);
 }
 
@@ -298,18 +297,46 @@ function parseFieldSet(parser_state, field_name) {
  * @returns {ParseTermResult}
  */
 function parseOperatorTerm(parser_state, start_index, field_or_relation_name) {
-  const prefix_term = parsePrefixTerm(parser_state, field_or_relation_name);
+  const field_set = parseFieldSet(
+    parser_state,
+    start_index,
+    field_or_relation_name,
+  );
+
+  if (field_set) {
+    return field_set;
+  }
+
+  const prefix_term = parsePrefixTerm(
+    parser_state,
+    start_index,
+    field_or_relation_name,
+  );
 
   if (prefix_term) {
     return prefix_term;
   }
 
-  const contains_term = parseContainsTerm(parser_state, field_or_relation_name);
+  const contains_term = parseContainsTerm(
+    parser_state,
+    start_index,
+    field_or_relation_name,
+  );
 
   if (contains_term) {
     return contains_term;
   }
 
+  const comparison_term = parseFieldComparisonTerm(
+    parser_state,
+    start_index,
+    field_or_relation_name,
+  );
+
+  if (comparison_term) {
+    return comparison_term;
+  }
+
   const equality_term = parseEqualityTerm(
     parser_state,
     start_index,
@@ -395,39 +422,51 @@ function parseSetOperator(parser_state) {
 
 /**
  * @param {ParserState} parser_state
+ * @param {number} start_index
  * @param {string} field_name
  * @returns {ParseTermResult | null}
  */
-function parsePrefixTerm(parser_state, field_name) {
-  if (field_name !== 'id' && field_name !== 'path') {
-    return null;
-  }
-
+function parsePrefixTerm(parser_state, start_index, field_name) {
   if (!consumeOperator(parser_state, '^=')) {
     return null;
   }
 
+  skipWhitespace(parser_state);
   const value = parseBareValue(parser_state);
 
   return value
-    ? success({ field_name, kind: 'field', operator: '^=', value })
+    ? success({
+        column: start_index + 1,
+        field_name,
+        kind: 'field',
+        operator: '^=',
+        value,
+      })
     : failToken(parser_state);
 }
 
 /**
  * @param {ParserState} parser_state
+ * @param {number} start_index
  * @param {string} field_name
  * @returns {ParseTermResult | null}
  */
-function parseContainsTerm(parser_state, field_name) {
-  if (field_name !== 'title' || !consumeOperator(parser_state, '~')) {
+function parseContainsTerm(parser_state, start_index, field_name) {
+  if (!consumeOperator(parser_state, '~')) {
     return null;
   }
 
+  skipWhitespace(parser_state);
   const value = parseBareValue(parser_state);
 
   return value
-    ? success({ field_name: 'title', kind: 'field', operator: '~', value })
+    ? success({
+        column: start_index + 1,
+        field_name,
+        kind: 'field',
+        operator: '~',
+        value,
+      })
     : failToken(parser_state);
 }
 
@@ -442,14 +481,20 @@ function parseEqualityTerm(parser_state, start_index, field_or_relation_name) {
     return null;
   }
 
+  skipWhitespace(parser_state);
   const value = parseBareValue(parser_state);
 
   if (!value) {
     return failToken(parser_state);
   }
 
-  if (isExactMatchField(field_or_relation_name)) {
+  if (
+    field_or_relation_name.startsWith('$') ||
+    field_or_relation_name === 'title' ||
+    !value.includes(':')
+  ) {
     return success({
+      column: start_index + 1,
       field_name: field_or_relation_name,
       kind: 'field',
       operator: '=',
@@ -457,17 +502,54 @@ function parseEqualityTerm(parser_state, start_index, field_or_relation_name) {
     });
   }
 
-  if (value.includes(':')) {
-    return success({
-      column: start_index + 1,
-      kind: 'relation_target',
-      relation_name: field_or_relation_name,
-      target_id: value,
-    });
+  return success({
+    column: start_index + 1,
+    kind: 'relation_target',
+    relation_name: field_or_relation_name,
+    target_id: value,
+  });
+}
+
+/**
+ * @param {ParserState} parser_state
+ * @param {number} start_index
+ * @param {string} field_name
+ * @returns {ParseTermResult | null}
+ */
+function parseFieldComparisonTerm(parser_state, start_index, field_name) {
+  const operator = parseFieldComparisonOperator(parser_state);
+
+  if (!operator) {
+    return null;
   }
 
-  parser_state.index = start_index;
-  return failToken(parser_state);
+  skipWhitespace(parser_state);
+  const value = parseBareValue(parser_state);
+
+  if (!value) {
+    return failToken(parser_state);
+  }
+
+  return success({
+    column: start_index + 1,
+    field_name,
+    kind: 'field',
+    operator,
+    value,
+  });
+}
+
+/**
+ * @param {ParserState} parser_state
+ * @returns {'!=' | '<=' | '>=' | '<' | '>' | null}
+ */
+function parseFieldComparisonOperator(parser_state) {
+  /** @type {Array<'!=' | '<=' | '>=' | '<' | '>'>} */
+  const comparisons = ['!=', '<=', '>=', '<', '>'];
+
+  return (
+    comparisons.find((value) => consumeOperator(parser_state, value)) ?? null
+  );
 }
 
 /**
@@ -526,7 +608,7 @@ function parseComparison(parser_state) {
  * @returns {string | null}
  */
 function parseIdentifier(parser_state) {
-  return readMatch(parser_state, /^[a-z_]+/u);
+  return readMatch(parser_state, /^\$?[a-z_][a-z0-9_]*/u);
 }
 
 /**
@@ -643,22 +725,6 @@ function isAtEnd(parser_state) {
   return parser_state.index >= parser_state.where_clause.length;
 }
 
-/**
- * @param {string} field_name
- * @returns {field_name is ParsedFieldName}
- */
-function isSupportedFieldName(field_name) {
-  return ['id', 'kind', 'path', 'status', 'title'].includes(field_name);
-}
-
-/**
- * @param {string} field_name
- * @returns {field_name is 'id' | 'kind' | 'path' | 'status'}
- */
-function isExactMatchField(field_name) {
-  return ['id', 'kind', 'path', 'status'].includes(field_name);
-}
-
 /**
  * @param {ParsedTerm} term
  * @returns {ParseTermResult}

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';

package/lib/patram-cli.js

@@ -10,6 +10,7 @@ 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';
@@ -36,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';
@@ -43,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
@@ -94,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);
   }
@@ -140,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,
@@ -205,6 +216,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 +239,31 @@ 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 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
@@ -365,6 +396,7 @@ async function runShowCommand(parsed_command, io_context) {
     createShowOutputView(show_output.value, {
       derived_summary_evaluator,
       graph_nodes: project_graph_result.graph.nodes,
+      repo_config: project_graph_result.config,
     }),
   );
 
@@ -396,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 (