patram 0.2.0 → 0.4.0

package/lib/check-directive-value.js

@@ -0,0 +1,291 @@
+/**
+ * @import { DirectiveTypeConfig, MetadataDirectiveRuleConfig, PatramDiagnostic, PatramRepoConfig } from './load-patram-config.types.ts';
+ * @import { PatramClaim } from './parse-claims.types.ts';
+ * @import { MappingDefinition } from './patram-config.types.ts';
+ */
+
+import { resolveTargetReference } from './build-graph-identity.js';
+import { createOriginDiagnostic } from './directive-diagnostics.js';
+import {
+  formatQuotedList,
+  getInvalidTypeMessage,
+  isDirectiveValueValid,
+} from './directive-type-rules.js';
+
+/**
+ * Check one directive claim value against typed validation rules.
+ *
+ * @param {PatramClaim} claim
+ * @param {string} directive_name
+ * @param {Record<string, MappingDefinition>} mappings
+ * @param {PatramRepoConfig} repo_config
+ * @param {MetadataDirectiveRuleConfig | undefined} _directive_rule
+ * @param {Map<string, string>} document_entity_keys
+ * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
+ * @param {Set<string>} document_paths
+ * @returns {PatramDiagnostic[]}
+ */
+export function checkDirectiveValue(
+  claim,
+  directive_name,
+  mappings,
+  repo_config,
+  _directive_rule,
+  document_entity_keys,
+  document_node_references,
+  document_paths,
+) {
+  const mapping_definition = resolveDirectiveMapping(mappings, claim);
+  const validation_field_name = getDirectiveValidationFieldName(
+    directive_name,
+    mapping_definition,
+  );
+
+  if (!validation_field_name || typeof claim.value !== 'string') {
+    return [];
+  }
+
+  if (validation_field_name === '$class') {
+    return checkClassValue(claim, directive_name, repo_config);
+  }
+
+  if (isStructuralDirectiveField(validation_field_name)) {
+    return [];
+  }
+
+  const type_definition = repo_config.fields?.[validation_field_name];
+
+  if (!type_definition) {
+    return [];
+  }
+
+  if (type_definition.type === 'enum') {
+    return checkEnumValue(claim, directive_name, type_definition.values);
+  }
+
+  const type_diagnostic = createInvalidTypeDiagnostic(
+    claim,
+    directive_name,
+    type_definition,
+    claim.value,
+  );
+
+  if (type_diagnostic) {
+    return [type_diagnostic];
+  }
+
+  return createPathClassDiagnostics(
+    claim,
+    directive_name,
+    mappings,
+    repo_config,
+    type_definition,
+    document_entity_keys,
+    document_node_references,
+    document_paths,
+  );
+}
+
+/**
+ * @param {PatramClaim} claim
+ * @param {string} directive_name
+ * @param {PatramRepoConfig} repo_config
+ * @returns {PatramDiagnostic[]}
+ */
+function checkClassValue(claim, directive_name, repo_config) {
+  if (
+    typeof claim.value !== 'string' ||
+    repo_config.classes?.[claim.value] !== undefined
+  ) {
+    return [];
+  }
+
+  return [
+    createOriginDiagnostic(
+      claim,
+      'directive.invalid_enum',
+      `Directive "${directive_name}" must reference a configured class.`,
+    ),
+  ];
+}
+
+/**
+ * @param {PatramClaim} claim
+ * @param {string} directive_name
+ * @param {string[]} allowed_values
+ * @returns {PatramDiagnostic[]}
+ */
+function checkEnumValue(claim, directive_name, allowed_values) {
+  if (typeof claim.value !== 'string' || allowed_values.includes(claim.value)) {
+    return [];
+  }
+
+  return [
+    createOriginDiagnostic(
+      claim,
+      'directive.invalid_enum',
+      `Directive "${directive_name}" must be one of ${formatQuotedList(allowed_values)}.`,
+    ),
+  ];
+}
+
+/**
+ * @param {PatramClaim} claim
+ * @param {string} directive_name
+ * @param {Exclude<DirectiveTypeConfig, { type: 'enum' }>} type_definition
+ * @param {string} directive_value
+ * @returns {PatramDiagnostic | null}
+ */
+function createInvalidTypeDiagnostic(
+  claim,
+  directive_name,
+  type_definition,
+  directive_value,
+) {
+  if (isDirectiveValueValid(type_definition, directive_value)) {
+    return null;
+  }
+
+  return createOriginDiagnostic(
+    claim,
+    'directive.invalid_type',
+    getInvalidTypeMessage(directive_name, type_definition.type),
+  );
+}
+
+/**
+ * @param {PatramClaim} claim
+ * @param {string} directive_name
+ * @param {Record<string, MappingDefinition>} mappings
+ * @param {PatramRepoConfig} repo_config
+ * @param {Exclude<DirectiveTypeConfig, { type: 'enum' }>} type_definition
+ * @param {Map<string, string>} document_entity_keys
+ * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
+ * @param {Set<string>} document_paths
+ * @returns {PatramDiagnostic[]}
+ */
+function createPathClassDiagnostics(
+  claim,
+  directive_name,
+  mappings,
+  repo_config,
+  type_definition,
+  document_entity_keys,
+  document_node_references,
+  document_paths,
+) {
+  if (
+    type_definition.type !== 'path' ||
+    type_definition.path_class === undefined ||
+    isDirectivePathInClass(
+      mappings,
+      claim,
+      type_definition.path_class,
+      document_entity_keys,
+      document_node_references,
+      document_paths,
+      repo_config,
+    )
+  ) {
+    return [];
+  }
+
+  return [
+    createOriginDiagnostic(
+      claim,
+      'directive.invalid_path_class',
+      `Directive "${directive_name}" must point to path class "${type_definition.path_class}".`,
+    ),
+  ];
+}
+
+/**
+ * @param {Record<string, MappingDefinition>} mappings
+ * @param {PatramClaim} claim
+ * @param {string} path_class_name
+ * @param {Map<string, string>} document_entity_keys
+ * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
+ * @param {Set<string>} document_paths
+ * @param {PatramRepoConfig} repo_config
+ * @returns {boolean}
+ */
+function isDirectivePathInClass(
+  mappings,
+  claim,
+  path_class_name,
+  document_entity_keys,
+  document_node_references,
+  document_paths,
+  repo_config,
+) {
+  const path_class_definition = repo_config.path_classes?.[path_class_name];
+
+  if (!path_class_definition) {
+    return true;
+  }
+
+  const mapping_definition = resolveDirectiveMapping(mappings, claim);
+  const target_kind = mapping_definition?.emit?.target_class ?? 'document';
+  const resolved_target = resolveTargetReference(
+    target_kind,
+    'path',
+    claim,
+    document_entity_keys,
+    document_node_references,
+    document_paths,
+  );
+
+  if (!resolved_target.path) {
+    return false;
+  }
+
+  return path_class_definition.prefixes.some((prefix) =>
+    resolved_target.path?.startsWith(prefix),
+  );
+}
+
+/**
+ * @param {Record<string, MappingDefinition>} mappings
+ * @param {PatramClaim} claim
+ * @returns {MappingDefinition | null}
+ */
+function resolveDirectiveMapping(mappings, claim) {
+  if (!claim.name || !claim.parser) {
+    return null;
+  }
+
+  return mappings[`${claim.parser}.directive.${claim.name}`] ?? null;
+}
+
+/**
+ * @param {string} directive_name
+ * @param {MappingDefinition | null} mapping_definition
+ * @returns {string}
+ */
+function getDirectiveValidationFieldName(directive_name, mapping_definition) {
+  if (mapping_definition?.node?.field) {
+    return mapping_definition.node.field;
+  }
+
+  return directive_name;
+}
+
+/**
+ * @param {string} field_name
+ * @returns {boolean}
+ */
+function isStructuralDirectiveField(field_name) {
+  return (
+    field_name === '$class' ||
+    field_name === '$id' ||
+    field_name === '$path' ||
+    field_name === 'title'
+  );
+}
+
+/**
+ * @param {PatramClaim} claim
+ * @param {string} code
+ * @param {string} message
+ * @returns {PatramDiagnostic}
+ */

package/lib/check-graph.js

@@ -1,8 +1,11 @@
 /**
  * @import { BuildGraphResult, GraphEdge, GraphNode } from './build-graph.types.ts';
- * @import { PatramDiagnostic } from './load-patram-config.types.ts';
+ * @import { PatramDiagnostic, PatramRepoConfig } from './load-patram-config.types.ts';
+ * @import { PatramClaim } from './parse-claims.types.ts';
  */
 
+import { checkDirectiveMetadata } from './check-directive-metadata.js';
+
 /**
  * Graph validation.
  *
@@ -24,9 +27,11 @@
  *
  * @param {BuildGraphResult} graph
  * @param {string[]} existing_file_paths
+ * @param {PatramRepoConfig} [repo_config]
+ * @param {PatramClaim[]} [claims]
  * @returns {PatramDiagnostic[]}
  */
-export function checkGraph(graph, existing_file_paths) {
+export function checkGraph(graph, existing_file_paths, repo_config, claims) {
   /** @type {PatramDiagnostic[]} */
   const diagnostics = [];
   const existing_file_path_set = new Set(existing_file_paths);
@@ -54,6 +59,17 @@ export function checkGraph(graph, existing_file_paths) {
     );
   }
 
+  if (repo_config && claims) {
+    diagnostics.push(
+      ...checkDirectiveMetadata(
+        graph,
+        repo_config,
+        claims,
+        existing_file_paths,
+      ),
+    );
+  }
+
   return diagnostics;
 }
 
@@ -102,15 +118,17 @@ function collectBrokenLinkDiagnostics(
   target_node,
   existing_file_path_set,
 ) {
+  const target_path = target_node.$path ?? target_node.path;
+
   if (graph_edge.relation !== 'links_to') {
     return;
   }
 
-  if (target_node.kind !== 'document' || !target_node.path) {
+  if (!target_path) {
     return;
   }
 
-  if (existing_file_path_set.has(target_node.path)) {
+  if (existing_file_path_set.has(target_path)) {
     return;
   }
 
@@ -118,7 +136,7 @@ function collectBrokenLinkDiagnostics(
     createDiagnostic(
       graph_edge,
       'graph.link_broken',
-      `Document link target "${target_node.path}" was not found.`,
+      `Document link target "${target_path}" was not found.`,
     ),
   );
 }

package/lib/cli-help-metadata.js

@@ -47,6 +47,7 @@
 
 export const COMMAND_NAMES = /** @type {const} */ ([
   'check',
+  'fields',
   'query',
   'queries',
   'show',
@@ -108,6 +109,33 @@ const COMMAND_DEFINITIONS = {
       'Validate a project, directory, or file and report graph diagnostics.',
     usage_lines: ['patram check [path] [options]'],
   },
+  fields: {
+    allowed_option_names: new Set(),
+    examples: ['patram fields', 'patram fields --json'],
+    extra_positionals_message: 'Fields does not accept positional arguments.',
+    help_topics: [],
+    max_positionals: 0,
+    min_positionals: 0,
+    missing_argument_examples: [],
+    missing_argument_label: null,
+    missing_usage_lines: ['patram fields'],
+    option_column_width: 10,
+    options: [
+      {
+        description: 'Print plain text output',
+        label: '--plain',
+      },
+      {
+        description: 'Print JSON output',
+        label: '--json',
+      },
+    ],
+    related: ['query', 'check'],
+    root_summary: 'Discover likely field schema from source claims',
+    summary:
+      'Discover likely metadata fields, multiplicity, and class usage from source claims.',
+    usage_lines: ['patram fields [options]'],
+  },
   query: {
     allowed_option_names: new Set([
       'explain',
@@ -120,10 +148,10 @@ const COMMAND_DEFINITIONS = {
       'patram query active-plans',
       'patram query --where "tracked_in=doc:docs/plans/v0/worktracking-agent-guidance.md"',
       'patram query --where "status not in [done, dropped, superseded]"',
-      'patram query --where "kind=plan and none(in:tracked_in, kind=decision)"',
-      'patram query --where "count(in:decided_by, kind=task) = 0"',
+      'patram query --where "$class=plan and none(in:tracked_in, $class=decision)"',
+      'patram query --where "count(in:decided_by, $class=task) = 0"',
       'patram query ready-tasks --explain',
-      'patram query --where "kind=decision and status=accepted and count(in:decided_by, kind=task) = 0" --lint',
+      'patram query --where "$class=decision and status=accepted and count(in:decided_by, $class=task) = 0" --lint',
       'patram query active-plans --limit 10 --offset 20',
     ],
     extra_positionals_message:
@@ -176,8 +204,8 @@ const COMMAND_DEFINITIONS = {
     summary:
       'Run a stored query or an ad hoc where clause against graph nodes.',
     syntax_lines: [
-      'id=<value> | kind=<value> | path=<value> | status=<value>',
-      'id^=<prefix> | path^=<prefix> | title~<text>',
+      '$id=<value> | $class=<value> | $path=<value> | status=<value>',
+      '$id^=<prefix> | $path^=<prefix> | title~<text>',
       '<field> in [<value>, ...] | <field> not in [<value>, ...]',
       '<relation>:* | <relation>=<target-id>',
       'any(<traversal>, <term> and <term>)',
@@ -251,15 +279,17 @@ const COMMAND_DEFINITIONS = {
 const HELP_TOPIC_DEFINITIONS = {
   'query-language': {
     examples: [
-      'kind=decision and status=accepted',
-      'path^=docs/plans/',
+      '$class=decision and status=accepted',
+      '$class=task or status=done',
+      '($class=task or status=blocked) and title~Show',
+      '$path^=docs/plans/',
       'title~query',
       'tracked_in=doc:docs/plans/v0/worktracking-agent-guidance.md',
       'implements_command=command:query',
       'status not in [done, dropped, superseded]',
-      'any(in:tracked_in, kind=task and status in [pending, ready, in_progress, blocked])',
-      'none(in:tracked_in, kind=decision)',
-      'count(in:decided_by, kind=task) = 0',
+      'any(in:tracked_in, $class=task and status in [pending, ready, in_progress, blocked])',
+      'none(in:tracked_in, $class=decision)',
+      'count(in:decided_by, $class=task) = 0',
       'not uses_term=term:graph',
     ],
     lead: 'Query language filters graph nodes with field, relation, traversal, and aggregate terms.',
@@ -269,7 +299,7 @@ const HELP_TOPIC_DEFINITIONS = {
         label: '=',
       },
       {
-        description: 'Prefix match for id and path',
+        description: 'Prefix match for structural id and path',
         label: '^=',
       },
       {
@@ -292,6 +322,14 @@ const HELP_TOPIC_DEFINITIONS = {
         description: 'Combine terms',
         label: 'and',
       },
+      {
+        description: 'Match either side',
+        label: 'or',
+      },
+      {
+        description: 'Group boolean expressions',
+        label: '( )',
+      },
       {
         description: 'Count comparisons',
         label: '!= < > >= <=',
@@ -316,15 +354,15 @@ const HELP_TOPIC_DEFINITIONS = {
       },
     ],
     terms: [
-      'Exact match: id, kind, path, status',
-      'Prefix match: id, path',
+      'Exact match: $id, $class, $path, status',
+      'Prefix match: $id, $path',
       'Contains text: title',
-      'Set membership: id, kind, path, status, title',
+      'Set membership: $id, $class, $path, status, title',
     ],
     usage_lines: [
       '<field>=<value>',
-      'id^=<prefix>',
-      'path^=<prefix>',
+      '$id^=<prefix>',
+      '$path^=<prefix>',
       'title~<text>',
       '<field> in [<value>, ...]',
       '<field> not in [<value>, ...]',
@@ -335,6 +373,8 @@ const HELP_TOPIC_DEFINITIONS = {
       'count(<traversal>, <term> and <term>) <comparison> <number>',
       'not <term>',
       '<term> and <term>',
+      '<term> or <term>',
+      '(<expression>)',
     ],
   },
 };

package/lib/command-output.js

@@ -45,6 +45,20 @@ export async function writeCommandOutput(
     parsed_command,
   );
 
+  await writeRenderedCommandOutput(io_context, parsed_command, rendered_output);
+}
+
+/**
+ * @param {{ stdout: { isTTY?: boolean, write(chunk: string): boolean }, write_paged_output?: (output_text: string) => Promise<void> }} io_context
+ * @param {ParsedCliArguments} parsed_command
+ * @param {string} rendered_output
+ * @returns {Promise<void>}
+ */
+export async function writeRenderedCommandOutput(
+  io_context,
+  parsed_command,
+  rendered_output,
+) {
   if (shouldPageCommandOutput(parsed_command, io_context.stdout)) {
     await writeInteractiveOutput(io_context, rendered_output);
 
@@ -62,7 +76,8 @@ export async function writeCommandOutput(
 export function shouldPageCommandOutput(parsed_command, output_stream) {
   return (
     output_stream.isTTY === true &&
-    (parsed_command.command_name === 'query' ||
+    (parsed_command.command_name === 'fields' ||
+      parsed_command.command_name === 'query' ||
       parsed_command.command_name === 'show')
   );
 }

package/lib/derived-summary.js

@@ -34,13 +34,15 @@ import { queryGraph } from './query-graph.js';
  * @returns {DerivedSummaryEvaluator}
  */
 export function createDerivedSummaryEvaluator(repo_config, graph) {
-  const summary_by_kind = createSummaryByKind(repo_config.derived_summaries);
+  const summary_by_class = createSummaryByClass(repo_config.derived_summaries);
   /** @type {Map<string, Set<string>>} */
   const matching_node_id_cache = new Map();
 
   return {
     evaluate(graph_node) {
-      const configured_summary = summary_by_kind.get(graph_node.kind);
+      const configured_summary = summary_by_class.get(
+        graph_node.$class ?? 'document',
+      );
 
       if (!configured_summary) {
         return null;
@@ -255,24 +257,24 @@ function parseTraversal(traversal_text) {
  * @param {PatramRepoConfig['derived_summaries']} derived_summaries
  * @returns {Map<string, { definition: DerivedSummaryConfig, name: string }>}
  */
-function createSummaryByKind(derived_summaries) {
+function createSummaryByClass(derived_summaries) {
   /** @type {Map<string, { definition: DerivedSummaryConfig, name: string }>} */
-  const summary_by_kind = new Map();
+  const summary_by_class = new Map();
 
   if (!derived_summaries) {
-    return summary_by_kind;
+    return summary_by_class;
   }
 
   for (const [summary_name, summary_definition] of Object.entries(
     derived_summaries,
   )) {
-    for (const kind_name of summary_definition.kinds) {
-      summary_by_kind.set(kind_name, {
+    for (const class_name of summary_definition.classes) {
+      summary_by_class.set(class_name, {
         definition: summary_definition,
         name: summary_name,
       });
     }
   }
 
-  return summary_by_kind;
+  return summary_by_class;
 }

package/lib/directive-diagnostics.js

@@ -0,0 +1,38 @@
+/**
+ * @import { PatramDiagnostic } from './load-patram-config.types.ts';
+ * @import { PatramClaim } from './parse-claims.types.ts';
+ */
+
+/**
+ * @param {PatramClaim} claim
+ * @param {string} code
+ * @param {string} message
+ * @returns {PatramDiagnostic}
+ */
+export function createOriginDiagnostic(claim, code, message) {
+  return {
+    code,
+    column: claim.origin.column,
+    level: 'error',
+    line: claim.origin.line,
+    message,
+    path: claim.origin.path,
+  };
+}
+
+/**
+ * @param {string} document_path
+ * @param {string} code
+ * @param {string} message
+ * @returns {PatramDiagnostic}
+ */
+export function createDocumentDiagnostic(document_path, code, message) {
+  return {
+    code,
+    column: 1,
+    level: 'error',
+    line: 1,
+    message,
+    path: document_path,
+  };
+}