patram 0.8.0 → 0.9.0

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' },

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

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;