patram 0.8.0 → 0.10.0

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

@@ -3,9 +3,11 @@
  * @import {
  *   CliCommandName,
  *   CliHelpTopicName,
- * } from './parse-cli-arguments.types.ts';
+ * } from './arguments.types.ts';
  */
 
+import { findCloseMatch } from '../find-close-match.js';
+
 /**
  * @typedef {{
  *   description: string,
@@ -45,7 +47,7 @@
  * }} CliHelpTopicDefinition
  */
 
-export const COMMAND_NAMES = /** @type {const} */ ([
+const COMMAND_NAMES = /** @type {const} */ ([
   'check',
   'fields',
   'query',
@@ -54,7 +56,7 @@ export const COMMAND_NAMES = /** @type {const} */ ([
   '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',
@@ -284,14 +286,14 @@ const COMMAND_DEFINITIONS = {
   },
   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>'],
@@ -532,100 +534,3 @@ function listOptionLabels(command_name) {
 
   return [...option_labels];
 }
-
-/**
- * @param {string} input_text
- * @param {readonly string[]} candidates
- * @returns {string | undefined}
- */
-function findCloseMatch(input_text, candidates) {
-  let best_candidate;
-  let best_score = 0;
-
-  for (const candidate of candidates) {
-    const score = scoreCandidate(input_text, candidate);
-
-    if (score > best_score) {
-      best_candidate = candidate;
-      best_score = score;
-    }
-  }
-
-  if (best_score < 0.6) {
-    return undefined;
-  }
-
-  return best_candidate;
-}
-
-/**
- * @param {string} input_text
- * @param {string} candidate
- * @returns {number}
- */
-function scoreCandidate(input_text, candidate) {
-  const max_length = Math.max(input_text.length, candidate.length);
-
-  if (max_length === 0) {
-    return 1;
-  }
-
-  return (
-    1 - calculateDamerauLevenshteinDistance(input_text, candidate) / max_length
-  );
-}
-
-/**
- * @param {string} left_text
- * @param {string} right_text
- * @returns {number}
- */
-function calculateDamerauLevenshteinDistance(left_text, right_text) {
-  /** @type {number[][]} */
-  const matrix = Array.from({ length: left_text.length + 1 }, () =>
-    Array(right_text.length + 1).fill(0),
-  );
-
-  for (let left_index = 0; left_index <= left_text.length; left_index += 1) {
-    matrix[left_index][0] = left_index;
-  }
-
-  for (
-    let right_index = 0;
-    right_index <= right_text.length;
-    right_index += 1
-  ) {
-    matrix[0][right_index] = right_index;
-  }
-
-  for (let left_index = 1; left_index <= left_text.length; left_index += 1) {
-    for (
-      let right_index = 1;
-      right_index <= right_text.length;
-      right_index += 1
-    ) {
-      const substitution_cost =
-        left_text[left_index - 1] === right_text[right_index - 1] ? 0 : 1;
-
-      matrix[left_index][right_index] = Math.min(
-        matrix[left_index - 1][right_index] + 1,
-        matrix[left_index][right_index - 1] + 1,
-        matrix[left_index - 1][right_index - 1] + substitution_cost,
-      );
-
-      if (
-        left_index > 1 &&
-        right_index > 1 &&
-        left_text[left_index - 1] === right_text[right_index - 2] &&
-        left_text[left_index - 2] === right_text[right_index - 1]
-      ) {
-        matrix[left_index][right_index] = Math.min(
-          matrix[left_index][right_index],
-          matrix[left_index - 2][right_index - 2] + 1,
-        );
-      }
-    }
-  }
-
-  return matrix[left_text.length][right_text.length];
-}

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' },
@@ -67,9 +67,7 @@ export function validateHelpCommandLine(command_line) {
   }
 
   if (command_line.positionals.length > 2) {
-    return createMessageParseError(
-      'Help accepts at most one topic or command.',
-    );
+    return createUnexpectedArgumentError('help', command_line.positionals[2]);
   }
 
   return null;
@@ -422,8 +420,9 @@ function validateCommandPositionals(command_name, command_positionals) {
   }
 
   if (command_positionals.length > command_definition.max_positionals) {
-    return createMessageParseError(
-      command_definition.extra_positionals_message,
+    return createUnexpectedArgumentError(
+      command_name,
+      command_positionals[command_definition.max_positionals],
     );
   }
 
@@ -451,3 +450,16 @@ function isKnownCommandOptionName(option_name) {
     option_name === 'where'
   );
 }
+
+/**
+ * @param {'help' | CliCommandName} command_name
+ * @param {string | undefined} token
+ * @returns {CliParseError}
+ */
+function createUnexpectedArgumentError(command_name, token) {
+  return {
+    code: 'unexpected_argument',
+    command_name,
+    token: token ?? '',
+  };
+}

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
@@ -75,6 +75,20 @@ export function renderCliParseError(parse_error) {
     );
   }
 
+  if (parse_error.code === 'unexpected_argument') {
+    return renderUnexpectedArgumentError(
+      parse_error.command_name,
+      parse_error.token,
+    );
+  }
+
+  if (parse_error.code === 'unknown_stored_query') {
+    return renderUnknownStoredQueryError(
+      parse_error.name,
+      parse_error.suggestion,
+    );
+  }
+
   return `${parse_error.message}\n`;
 }
 
@@ -326,6 +340,49 @@ function renderMissingRequiredArgumentError(command_name, argument_label) {
   ]);
 }
 
+/**
+ * @param {'help' | CliCommandName} command_name
+ * @param {string} invalid_token
+ * @returns {string}
+ */
+function renderUnexpectedArgumentError(command_name, invalid_token) {
+  return joinOutputLines([
+    `Unexpected argument: ${invalid_token}`,
+    '',
+    'Usage:',
+    ...indentLines(getUnexpectedArgumentUsageLines(command_name)),
+    '',
+    'Next:',
+    `  ${renderUnexpectedArgumentNext(command_name)}`,
+  ]);
+}
+
+/**
+ * @param {string} stored_query_name
+ * @param {string | undefined} suggestion
+ * @returns {string}
+ */
+function renderUnknownStoredQueryError(stored_query_name, suggestion) {
+  if (suggestion) {
+    return joinOutputLines([
+      `Unknown stored query: ${stored_query_name}`,
+      '',
+      'Did you mean:',
+      `  ${suggestion}`,
+      '',
+      'Next:',
+      `  patram query ${suggestion}`,
+    ]);
+  }
+
+  return joinOutputLines([
+    `Unknown stored query: ${stored_query_name}`,
+    '',
+    'Next:',
+    '  patram queries',
+  ]);
+}
+
 /**
  * @param {string} invalid_token
  * @param {CliCommandName | CliHelpTopicName | undefined} suggestion
@@ -378,6 +435,30 @@ function renderCommandHelpPath(command_name) {
   return `patram help ${command_name}`;
 }
 
+/**
+ * @param {'help' | CliCommandName} command_name
+ * @returns {string}
+ */
+function renderUnexpectedArgumentNext(command_name) {
+  if (command_name === 'help') {
+    return 'patram --help';
+  }
+
+  return renderCommandHelpPath(command_name);
+}
+
+/**
+ * @param {'help' | CliCommandName} command_name
+ * @returns {string[]}
+ */
+function getUnexpectedArgumentUsageLines(command_name) {
+  if (command_name === 'help') {
+    return ['patram help [command]'];
+  }
+
+  return getCommandDefinition(command_name).usage_lines;
+}
+
 /**
  * @param {string[]} lines
  * @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;