patram 0.7.0 → 0.9.0

package/lib/{cli-help-metadata.js → cli/help-metadata.js}

@@ -3,7 +3,7 @@
  * @import {
  *   CliCommandName,
  *   CliHelpTopicName,
- * } from './parse-cli-arguments.types.ts';
+ * } from './arguments.types.ts';
  */
 
 /**
@@ -45,15 +45,16 @@
  * }} CliHelpTopicDefinition
  */
 
-export const COMMAND_NAMES = /** @type {const} */ ([
+const COMMAND_NAMES = /** @type {const} */ ([
   'check',
   'fields',
   'query',
   'queries',
+  'refs',
   'show',
 ]);
 
-export const HELP_TOPIC_NAMES = /** @type {const} */ (['query-language']);
+const HELP_TOPIC_NAMES = /** @type {const} */ (['query-language']);
 
 export const GLOBAL_OPTION_NAMES = new Set([
   'help',
@@ -146,12 +147,12 @@ const COMMAND_DEFINITIONS = {
     ]),
     examples: [
       '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 "$class=plan and none(in:tracked_in, $class=decision)"',
-      'patram query --where "count(in:decided_by, $class=task) = 0"',
+      "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 '$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 "$class=decision and status=accepted and count(in:decided_by, $class=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:
@@ -161,12 +162,12 @@ const COMMAND_DEFINITIONS = {
     min_positionals: 0,
     missing_argument_examples: [
       'patram query active-plans',
-      'patram query --where "tracked_in=doc:docs/plans/v0/worktracking-agent-guidance.md"',
+      "patram query --where 'tracked_in=doc:docs/plans/v0/worktracking-agent-guidance.md'",
     ],
-    missing_argument_label: '<name> or --where "<clause>"',
+    missing_argument_label: "<name> or --where '<clause>'",
     missing_usage_lines: [
       'patram query <name> [options]',
-      'patram query --where "<clause>" [options]',
+      "patram query --where '<clause>' [options]",
     ],
     option_column_width: 19,
     options: [
@@ -214,7 +215,7 @@ const COMMAND_DEFINITIONS = {
     ],
     usage_lines: [
       'patram query <name> [options]',
-      'patram query --where "<clause>" [options]',
+      "patram query --where '<clause>' [options]",
     ],
   },
   queries: {
@@ -243,16 +244,54 @@ const COMMAND_DEFINITIONS = {
     summary: 'List the stored queries defined in the project configuration.',
     usage_lines: ['patram queries [options]'],
   },
+  refs: {
+    allowed_option_names: new Set(['where']),
+    examples: [
+      'patram refs docs/decisions/query-language.md',
+      "patram refs docs/decisions/query-language.md --where '$class=document'",
+      'patram refs docs/decisions/query-language.md --json',
+    ],
+    extra_positionals_message: 'Refs accepts exactly one file path.',
+    help_topics: ['query-language'],
+    max_positionals: 1,
+    min_positionals: 1,
+    missing_argument_examples: [
+      'patram refs docs/decisions/query-language.md',
+      "patram refs docs/patram.md --where '$class=document'",
+    ],
+    missing_argument_label: '<file>',
+    missing_usage_lines: ['patram refs <file>'],
+    option_column_width: 19,
+    options: [
+      {
+        description: 'Filter incoming source nodes with a where clause',
+        label: '--where <clause>',
+      },
+      {
+        description: 'Print plain text output',
+        label: '--plain',
+      },
+      {
+        description: 'Print JSON output',
+        label: '--json',
+      },
+    ],
+    related: ['show', 'query'],
+    root_summary: 'Inspect incoming graph references for one file',
+    summary:
+      'Inspect incoming graph references for one file, grouped by relation.',
+    usage_lines: ['patram refs <file> [options]'],
+  },
   show: {
     allowed_option_names: new Set(),
-    examples: ['patram show docs/patram.md', 'patram show lib/patram-cli.js'],
+    examples: ['patram show docs/patram.md', 'patram show lib/cli/main.js'],
     extra_positionals_message: 'Show accepts exactly one file path.',
     help_topics: [],
     max_positionals: 1,
     min_positionals: 1,
     missing_argument_examples: [
       'patram show docs/patram.md',
-      'patram show lib/patram-cli.js',
+      'patram show lib/cli/main.js',
     ],
     missing_argument_label: '<file>',
     missing_usage_lines: ['patram show <file>'],
@@ -544,7 +583,7 @@ function scoreCandidate(input_text, candidate) {
 function calculateDamerauLevenshteinDistance(left_text, right_text) {
   /** @type {number[][]} */
   const matrix = Array.from({ length: left_text.length + 1 }, () =>
-    Array(right_text.length + 1).fill(0),
+    Array.from({ length: right_text.length + 1 }, () => 0),
   );
 
   for (let left_index = 0; left_index <= left_text.length; left_index += 1) {

package/lib/cli/main.js

@@ -0,0 +1,76 @@
+/**
+ * @import { ParsedCliCommandRequest } from './arguments.types.ts';
+ */
+import { renderCliParseError, renderHelpRequest } from './render-help.js';
+import { parseCliArguments } from './parse-arguments.js';
+import { runCheckCommand } from './commands/check.js';
+import { runFieldsCommand } from './commands/fields.js';
+import { runQueryCommand } from './commands/query.js';
+import { runQueriesCommand } from './commands/queries.js';
+import { runRefsCommand } from './commands/refs.js';
+import { runShowCommand } from './commands/show.js';
+
+/**
+ * Patram command execution flow.
+ *
+ * Loads repo state and routes `check`, `fields`, `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/refs.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-arguments.js}
+ * @see {@link ./commands/query.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(renderCliParseError(parsed_arguments.error));
+
+    return 1;
+  }
+
+  if (parsed_arguments.value.kind === 'help') {
+    io_context.stdout.write(renderHelpRequest(parsed_arguments.value));
+
+    return 0;
+  }
+
+  const parsed_command = /** @type {ParsedCliCommandRequest} */ (
+    parsed_arguments.value
+  );
+  const commandHandler = COMMAND_HANDLERS[parsed_command.command_name];
+
+  if (commandHandler) {
+    return commandHandler(parsed_command, io_context);
+  }
+
+  io_context.stderr.write('Unknown command.\n');
+
+  return 1;
+}
+const COMMAND_HANDLERS = {
+  check: runCheckCommand,
+  fields: runFieldsCommand,
+  queries: runQueriesCommand,
+  query: runQueryCommand,
+  refs: runRefsCommand,
+  show: runShowCommand,
+};

package/lib/{parse-cli-arguments-helpers.js → cli/parse-arguments-helpers.js}

@@ -1,9 +1,9 @@
 /* eslint-disable max-lines */
 /**
- * @typedef {import('./parse-cli-arguments.types.ts').CliCommandName} CliCommandName
- * @typedef {import('./parse-cli-arguments.types.ts').CliOutputMode} CliOutputMode
- * @typedef {import('./parse-cli-arguments.types.ts').CliParseError} CliParseError
- * @typedef {import('./parse-cli-arguments.types.ts').ParsedCliHelpRequest} ParsedCliHelpRequest
+ * @typedef {import('./arguments.types.ts').CliCommandName} CliCommandName
+ * @typedef {import('./arguments.types.ts').CliOutputMode} CliOutputMode
+ * @typedef {import('./arguments.types.ts').CliParseError} CliParseError
+ * @typedef {import('./arguments.types.ts').ParsedCliHelpRequest} ParsedCliHelpRequest
  * @typedef {{ kind: string, name?: string, rawName?: string, value?: string | boolean }} CliOptionToken
  * @typedef {{ color?: string, explain?: boolean, help?: boolean, json?: boolean, limit?: string, lint?: boolean, 'no-color'?: boolean, offset?: string, plain?: boolean, where?: string }} CliOptionValues
  * @typedef {{ option_tokens: CliOptionToken[], positionals: string[], values: CliOptionValues }} ParsedCommandLine
@@ -17,9 +17,9 @@ import {
   GLOBAL_OPTION_NAMES,
   isCommandName,
   isHelpTopicName,
-} from './cli-help-metadata.js';
-import { findInvalidColorMode } from './parse-cli-color-options.js';
-import { findInvalidQueryPagination } from './parse-cli-query-pagination.js';
+} from './help-metadata.js';
+import { findInvalidColorMode } from './color-options.js';
+import { findInvalidQueryPagination } from './query-pagination.js';
 
 export const CLI_OPTIONS = /** @type {const} */ ({
   color: { type: 'string' },
@@ -160,6 +160,10 @@ export function buildCommandArguments(
     return ['--where', parsed_values.where];
   }
 
+  if (command_name === 'refs' && parsed_values.where !== undefined) {
+    return [command_positionals[0], '--where', parsed_values.where];
+  }
+
   return command_positionals;
 }
 
@@ -305,7 +309,7 @@ function findMissingOptionValue(option_tokens) {
   for (const token of option_tokens) {
     if (token.name === 'where' && typeof token.value !== 'string') {
       return {
-        argument_label: '<name> or --where "<clause>"',
+        argument_label: "<name> or --where '<clause>'",
         code: 'missing_required_argument',
         command_name: 'query',
       };
@@ -401,11 +405,14 @@ function validateCommandPositionals(command_name, command_positionals) {
       };
     }
 
-    if (command_name === 'show' && command_definition.missing_argument_label) {
+    if (
+      (command_name === 'refs' || command_name === 'show') &&
+      command_definition.missing_argument_label
+    ) {
       return {
         argument_label: command_definition.missing_argument_label,
         code: 'missing_required_argument',
-        command_name: 'show',
+        command_name,
       };
     }
 
@@ -422,7 +429,7 @@ function validateCommandPositionals(command_name, command_positionals) {
 
   if (command_name === 'query' && command_positionals.length === 0) {
     return {
-      argument_label: '<name> or --where "<clause>"',
+      argument_label: "<name> or --where '<clause>'",
       code: 'missing_required_argument',
       command_name: 'query',
     };

package/lib/{parse-cli-arguments.js → cli/parse-arguments.js}

@@ -1,9 +1,9 @@
 /* eslint-disable max-lines-per-function */
 /**
- * @typedef {import('./parse-cli-arguments-helpers.js').CliOptionValues} CliOptionValues
- * @typedef {import('./parse-cli-arguments-helpers.js').ParsedCommandLine} ParsedCommandLine
- * @typedef {import('./parse-cli-arguments.types.ts').CliParseError} CliParseError
- * @typedef {import('./parse-cli-arguments.types.ts').ParseCliArgumentsResult} ParseCliArgumentsResult
+ * @typedef {import('./parse-arguments-helpers.js').CliOptionValues} CliOptionValues
+ * @typedef {import('./parse-arguments-helpers.js').ParsedCommandLine} ParsedCommandLine
+ * @typedef {import('./arguments.types.ts').CliParseError} CliParseError
+ * @typedef {import('./arguments.types.ts').ParseCliArgumentsResult} ParseCliArgumentsResult
  */
 
 import { parseArgs } from 'node:util';
@@ -23,10 +23,10 @@ import {
   validateHelpCommandLine,
   validateParsedCommand,
   validateRootCommandLine,
-} from './parse-cli-arguments-helpers.js';
-import { isCommandName } from './cli-help-metadata.js';
-import { resolveColorMode } from './parse-cli-color-options.js';
-import { buildQueryPagination } from './parse-cli-query-pagination.js';
+} from './parse-arguments-helpers.js';
+import { isCommandName } from './help-metadata.js';
+import { resolveColorMode } from './color-options.js';
+import { buildQueryPagination } from './query-pagination.js';
 
 /**
  * CLI argument parsing.
@@ -36,11 +36,11 @@ import { buildQueryPagination } from './parse-cli-query-pagination.js';
  *
  * Kind: cli
  * Status: active
- * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
- * Decided by: ../docs/decisions/cli-argument-parser.md
+ * Tracked in: ../../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../../docs/decisions/cli-argument-parser.md
  * @patram
- * @see {@link ./patram-cli.js}
- * @see {@link ../docs/decisions/cli-argument-parser.md}
+ * @see {@link ./main.js}
+ * @see {@link ../../docs/decisions/cli-argument-parser.md}
  */
 
 /**

package/lib/{parse-cli-query-pagination.js → cli/query-pagination.js}

@@ -1,6 +1,6 @@
 /**
- * @typedef {import('./parse-cli-arguments-helpers.js').CliOptionToken} CliOptionToken
- * @typedef {import('./parse-cli-arguments-helpers.js').CliOptionValues} CliOptionValues
+ * @typedef {import('./parse-arguments-helpers.js').CliOptionToken} CliOptionToken
+ * @typedef {import('./parse-arguments-helpers.js').CliOptionValues} CliOptionValues
  */
 
 /**

package/lib/{render-cli-help.js → cli/render-help.js}

@@ -5,8 +5,8 @@
  *   CliHelpTopicName,
  *   CliParseError,
  *   ParsedCliHelpRequest,
- * } from './parse-cli-arguments.types.ts';
- * @import { PatramDiagnostic } from './load-patram-config.types.ts';
+ * } from './arguments.types.ts';
+ * @import { PatramDiagnostic } from '../config/load-patram-config.types.ts';
  */
 
 import {
@@ -15,7 +15,7 @@ import {
   getRootHelpDefinition,
   listCommandNames,
   listHelpTopicNames,
-} from './cli-help-metadata.js';
+} from './help-metadata.js';
 
 /**
  * @param {ParsedCliHelpRequest} help_request
@@ -308,7 +308,7 @@ function renderInvalidCommandOptionError(command_name, invalid_token) {
 }
 
 /**
- * @param {'query' | 'show'} command_name
+ * @param {'query' | 'refs' | 'show'} command_name
  * @param {string} argument_label
  * @returns {string}
  */

package/lib/{resolve-output-mode.js → cli/resolve-output-mode.js}

@@ -1,6 +1,6 @@
 /**
- * @import { ParsedCliArguments } from './parse-cli-arguments.types.ts';
- * @import { ResolvedOutputMode } from './output-view.types.ts';
+ * @import { ParsedCliArguments } from './arguments.types.ts';
+ * @import { ResolvedOutputMode } from '../output/output-view.types.ts';
  */
 
 /**

package/lib/cli/test-helpers.js

@@ -0,0 +1,30 @@
+export function createIoContext() {
+  /** @type {{ stderr_chunks: string[], stdout_chunks: string[] }} */
+  const io_context = {
+    stderr_chunks: [],
+    stdout_chunks: [],
+  };
+
+  return {
+    ...io_context,
+    stderr: {
+      /**
+       * @param {string} chunk
+       */
+      write(chunk) {
+        io_context.stderr_chunks.push(chunk);
+        return true;
+      },
+    },
+    stdout: {
+      isTTY: false,
+      /**
+       * @param {string} chunk
+       */
+      write(chunk) {
+        io_context.stdout_chunks.push(chunk);
+        return true;
+      },
+    },
+  };
+}

package/lib/config/defaults.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @returns {PatramRepoConfig}
+ */
+export function createDefaultRepoConfig(): PatramRepoConfig;
+/**
+ * @param {PatramRepoConfig} repo_config
+ * @returns {PatramRepoConfig}
+ */
+export function normalizeRepoConfig(repo_config: PatramRepoConfig): PatramRepoConfig;
+import type { PatramRepoConfig } from './schema.js';

package/lib/config/defaults.js

@@ -0,0 +1,80 @@
+/**
+ * @import { PatramRepoConfig } from './schema.js';
+ */
+
+import { DEFAULT_INCLUDE_PATTERNS } from './source-file-defaults.js';
+
+/**
+ * @returns {PatramRepoConfig}
+ */
+export function createDefaultRepoConfig() {
+  return {
+    include: [...DEFAULT_INCLUDE_PATTERNS],
+    queries: {},
+  };
+}
+
+/**
+ * @param {PatramRepoConfig} repo_config
+ * @returns {PatramRepoConfig}
+ */
+export function normalizeRepoConfig(repo_config) {
+  /** @type {PatramRepoConfig} */
+  const normalized_config = {
+    include: [...repo_config.include],
+    queries: { ...repo_config.queries },
+  };
+
+  assignOptionalRepoConfigField(
+    normalized_config,
+    'classes',
+    repo_config.classes,
+  );
+  assignOptionalRepoConfigField(
+    normalized_config,
+    'derived_summaries',
+    repo_config.derived_summaries,
+  );
+  assignOptionalRepoConfigField(
+    normalized_config,
+    'fields',
+    repo_config.fields,
+  );
+  assignOptionalRepoConfigField(
+    normalized_config,
+    'mappings',
+    repo_config.mappings,
+  );
+  assignOptionalRepoConfigField(
+    normalized_config,
+    'path_classes',
+    repo_config.path_classes,
+  );
+  assignOptionalRepoConfigField(
+    normalized_config,
+    'relations',
+    repo_config.relations,
+  );
+
+  return normalized_config;
+}
+
+/**
+ * @template {Exclude<keyof PatramRepoConfig, 'include' | 'queries'>} TKey
+ * @param {PatramRepoConfig} normalized_config
+ * @param {TKey} field_name
+ * @param {unknown} field_value
+ */
+function assignOptionalRepoConfigField(
+  normalized_config,
+  field_name,
+  field_value,
+) {
+  if (field_value === undefined || field_value === null) {
+    return;
+  }
+
+  normalized_config[field_name] = /** @type {PatramRepoConfig[TKey]} */ (
+    field_value
+  );
+}

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

@@ -0,0 +1,76 @@
+/**
+ * Repo config loading.
+ *
+ * Reads `.patram.json`, applies defaults, and validates repo config and graph
+ * schema before command execution.
+ *
+ * Kind: config
+ * Status: active
+ * Tracked in: ../../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../../docs/decisions/single-config-file.md
+ * Decided by: ../../docs/decisions/optional-config-default-scan.md
+ * @patram
+ * @see {@link ./schema.js}
+ * @see {@link ./validation.js}
+ */
+/**
+ * @typedef {object} PatramDiagnostic
+ * @property {string} code
+ * @property {number} column
+ * @property {'error'} level
+ * @property {number} line
+ * @property {string} message
+ * @property {string} path
+ */
+/**
+ * @typedef {object} LoadPatramConfigResult
+ * @property {import('./schema.js').PatramRepoConfig | null} config
+ * @property {string} config_path
+ * @property {PatramDiagnostic[]} diagnostics
+ */
+/**
+ * @typedef {import('./schema.js').StoredQueryConfig} StoredQueryConfig
+ * @typedef {import('./schema.js').FieldDisplayConfig} FieldDisplayConfig
+ * @typedef {import('./schema.js').FieldQueryConfig} FieldQueryConfig
+ * @typedef {import('./schema.js').MetadataFieldConfig} MetadataFieldConfig
+ * @typedef {import('./schema.js').ClassFieldRuleConfig} ClassFieldRuleConfig
+ * @typedef {import('./schema.js').ClassSchemaConfig} ClassSchemaConfig
+ * @typedef {import('./schema.js').PathClassConfig} PathClassConfig
+ * @typedef {import('./schema.js').DerivedSummaryScalar} DerivedSummaryScalar
+ * @typedef {import('./schema.js').DerivedSummarySelectCaseConfig} DerivedSummarySelectCaseConfig
+ * @typedef {import('./schema.js').DerivedSummaryFieldConfig} DerivedSummaryFieldConfig
+ * @typedef {import('./schema.js').DerivedSummaryConfig} DerivedSummaryConfig
+ * @typedef {import('./schema.js').PatramRepoConfig} PatramRepoConfig
+ */
+/**
+ * Load and validate the repo Patram config.
+ *
+ * @param {string} [project_directory]
+ * @returns {Promise<LoadPatramConfigResult>}
+ */
+export function loadPatramConfig(project_directory?: string): Promise<LoadPatramConfigResult>;
+export type PatramDiagnostic = {
+    code: string;
+    column: number;
+    level: "error";
+    line: number;
+    message: string;
+    path: string;
+};
+export type LoadPatramConfigResult = {
+    config: import("./schema.js").PatramRepoConfig | null;
+    config_path: string;
+    diagnostics: PatramDiagnostic[];
+};
+export type StoredQueryConfig = import("./schema.js").StoredQueryConfig;
+export type FieldDisplayConfig = import("./schema.js").FieldDisplayConfig;
+export type FieldQueryConfig = import("./schema.js").FieldQueryConfig;
+export type MetadataFieldConfig = import("./schema.js").MetadataFieldConfig;
+export type ClassFieldRuleConfig = import("./schema.js").ClassFieldRuleConfig;
+export type ClassSchemaConfig = import("./schema.js").ClassSchemaConfig;
+export type PathClassConfig = import("./schema.js").PathClassConfig;
+export type DerivedSummaryScalar = import("./schema.js").DerivedSummaryScalar;
+export type DerivedSummarySelectCaseConfig = import("./schema.js").DerivedSummarySelectCaseConfig;
+export type DerivedSummaryFieldConfig = import("./schema.js").DerivedSummaryFieldConfig;
+export type DerivedSummaryConfig = import("./schema.js").DerivedSummaryConfig;
+export type PatramRepoConfig = import("./schema.js").PatramRepoConfig;