patram 0.7.0 → 0.9.0

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

@@ -1,45 +0,0 @@
-export type StoredQueryConfig = import('./load-patram-config.js').StoredQueryConfig;
-export type FieldDisplayConfig = import('./load-patram-config.js').FieldDisplayConfig;
-export type FieldQueryConfig = import('./load-patram-config.js').FieldQueryConfig;
-export type FieldValueTypeName = import('./load-patram-config.js').MetadataFieldConfig['type'];
-export type MetadataFieldConfig = import('./load-patram-config.js').MetadataFieldConfig;
-export type StringFieldConfig = Extract<MetadataFieldConfig, {
-    type: 'string';
-}>;
-export type IntegerFieldConfig = Extract<MetadataFieldConfig, {
-    type: 'integer';
-}>;
-export type EnumFieldConfig = Extract<MetadataFieldConfig, {
-    type: 'enum';
-}>;
-export type PathFieldConfig = Extract<MetadataFieldConfig, {
-    type: 'path';
-}>;
-export type GlobFieldConfig = Extract<MetadataFieldConfig, {
-    type: 'glob';
-}>;
-export type DateFieldConfig = Extract<MetadataFieldConfig, {
-    type: 'date';
-}>;
-export type DateTimeFieldConfig = Extract<MetadataFieldConfig, {
-    type: 'date_time';
-}>;
-export type ClassFieldRuleConfig = import('./load-patram-config.js').ClassFieldRuleConfig;
-export type DirectiveTypeConfig = MetadataFieldConfig;
-export type MetadataDirectiveRuleConfig = ClassFieldRuleConfig;
-export type ClassSchemaConfig = import('./load-patram-config.js').ClassSchemaConfig;
-export type MetadataSchemaConfig = ClassSchemaConfig;
-export type PathClassConfig = import('./load-patram-config.js').PathClassConfig;
-export type DerivedSummaryScalar = import('./load-patram-config.js').DerivedSummaryScalar;
-export type DerivedSummarySelectCaseConfig = import('./load-patram-config.js').DerivedSummarySelectCaseConfig;
-export type DerivedSummaryFieldConfig = import('./load-patram-config.js').DerivedSummaryFieldConfig;
-export type DerivedSummaryCountFieldConfig = Extract<DerivedSummaryFieldConfig, {
-    count: unknown;
-}>;
-export type DerivedSummarySelectFieldConfig = Extract<DerivedSummaryFieldConfig, {
-    select: unknown;
-}>;
-export type DerivedSummaryConfig = import('./load-patram-config.js').DerivedSummaryConfig;
-export type PatramRepoConfig = import('./load-patram-config.js').PatramRepoConfig;
-export type PatramDiagnostic = import('./load-patram-config.js').PatramDiagnostic;
-export type LoadPatramConfigResult = import('./load-patram-config.js').LoadPatramConfigResult;

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

@@ -1,56 +0,0 @@
-export type StoredQueryConfig =
-  import('./load-patram-config.js').StoredQueryConfig;
-export type FieldDisplayConfig =
-  import('./load-patram-config.js').FieldDisplayConfig;
-export type FieldQueryConfig =
-  import('./load-patram-config.js').FieldQueryConfig;
-export type FieldValueTypeName =
-  import('./load-patram-config.js').MetadataFieldConfig['type'];
-export type MetadataFieldConfig =
-  import('./load-patram-config.js').MetadataFieldConfig;
-export type StringFieldConfig = Extract<
-  MetadataFieldConfig,
-  { type: 'string' }
->;
-export type IntegerFieldConfig = Extract<
-  MetadataFieldConfig,
-  { type: 'integer' }
->;
-export type EnumFieldConfig = Extract<MetadataFieldConfig, { type: 'enum' }>;
-export type PathFieldConfig = Extract<MetadataFieldConfig, { type: 'path' }>;
-export type GlobFieldConfig = Extract<MetadataFieldConfig, { type: 'glob' }>;
-export type DateFieldConfig = Extract<MetadataFieldConfig, { type: 'date' }>;
-export type DateTimeFieldConfig = Extract<
-  MetadataFieldConfig,
-  { type: 'date_time' }
->;
-export type ClassFieldRuleConfig =
-  import('./load-patram-config.js').ClassFieldRuleConfig;
-export type DirectiveTypeConfig = MetadataFieldConfig;
-export type MetadataDirectiveRuleConfig = ClassFieldRuleConfig;
-export type ClassSchemaConfig =
-  import('./load-patram-config.js').ClassSchemaConfig;
-export type MetadataSchemaConfig = ClassSchemaConfig;
-export type PathClassConfig = import('./load-patram-config.js').PathClassConfig;
-export type DerivedSummaryScalar =
-  import('./load-patram-config.js').DerivedSummaryScalar;
-export type DerivedSummarySelectCaseConfig =
-  import('./load-patram-config.js').DerivedSummarySelectCaseConfig;
-export type DerivedSummaryFieldConfig =
-  import('./load-patram-config.js').DerivedSummaryFieldConfig;
-export type DerivedSummaryCountFieldConfig = Extract<
-  DerivedSummaryFieldConfig,
-  { count: unknown }
->;
-export type DerivedSummarySelectFieldConfig = Extract<
-  DerivedSummaryFieldConfig,
-  { select: unknown }
->;
-export type DerivedSummaryConfig =
-  import('./load-patram-config.js').DerivedSummaryConfig;
-export type PatramRepoConfig =
-  import('./load-patram-config.js').PatramRepoConfig;
-export type PatramDiagnostic =
-  import('./load-patram-config.js').PatramDiagnostic;
-export type LoadPatramConfigResult =
-  import('./load-patram-config.js').LoadPatramConfigResult;

package/lib/output-view.types.d.ts

@@ -1,80 +0,0 @@
-export type OutputDerivedValue = boolean | number | string | null;
-export interface OutputDerivedField {
-    name: string;
-    value: OutputDerivedValue;
-}
-export interface OutputDerivedSummary {
-    fields: OutputDerivedField[];
-    name: string;
-}
-export interface OutputMetadataField {
-    name: string;
-    value: string | string[];
-}
-export interface OutputViewSummary {
-    count: number;
-    kind: 'resolved_link_list' | 'result_list' | 'stored_query_list';
-}
-export interface QueryOutputViewSummary extends OutputViewSummary {
-    kind: 'result_list';
-    limit: number;
-    offset: number;
-    total_count: number;
-}
-export interface OutputNodeItem {
-    derived_summary?: OutputDerivedSummary;
-    fields: Record<string, string | string[]>;
-    id: string;
-    kind: 'node';
-    node_kind: string;
-    path?: string;
-    title: string;
-    visible_fields: OutputMetadataField[];
-}
-export interface OutputStoredQueryItem {
-    kind: 'stored_query';
-    name: string;
-    where: string;
-}
-export interface OutputResolvedLinkTarget {
-    derived_summary?: OutputDerivedSummary;
-    fields: Record<string, string | string[]>;
-    id: string;
-    kind: string;
-    path?: string;
-    title: string;
-    visible_fields: OutputMetadataField[];
-}
-export interface OutputResolvedLinkItem {
-    kind: 'resolved_link';
-    label: string;
-    reference: number;
-    target: OutputResolvedLinkTarget;
-}
-export interface QueryOutputView {
-    command: 'query';
-    hints: string[];
-    items: OutputNodeItem[];
-    summary: QueryOutputViewSummary;
-}
-export interface QueriesOutputView {
-    command: 'queries';
-    hints: string[];
-    items: OutputStoredQueryItem[];
-    summary: OutputViewSummary;
-}
-export interface ShowOutputView {
-    command: 'show';
-    document?: OutputNodeItem;
-    hints: string[];
-    items: OutputResolvedLinkItem[];
-    path: string;
-    rendered_source: string;
-    source: string;
-    summary: OutputViewSummary;
-}
-export type OutputView = QueryOutputView | QueriesOutputView | ShowOutputView;
-export interface ResolvedOutputMode {
-    color_enabled: boolean;
-    renderer_name: 'json' | 'plain' | 'rich';
-}

package/lib/output-view.types.ts

@@ -1,96 +0,0 @@
-import type { GraphNode } from './build-graph.types.ts';
-
-export type OutputDerivedValue = boolean | number | string | null;
-
-export interface OutputDerivedField {
-  name: string;
-  value: OutputDerivedValue;
-}
-
-export interface OutputDerivedSummary {
-  fields: OutputDerivedField[];
-  name: string;
-}
-
-export interface OutputMetadataField {
-  name: string;
-  value: string | string[];
-}
-
-export interface OutputViewSummary {
-  count: number;
-  kind: 'resolved_link_list' | 'result_list' | 'stored_query_list';
-}
-
-export interface QueryOutputViewSummary extends OutputViewSummary {
-  kind: 'result_list';
-  limit: number;
-  offset: number;
-  total_count: number;
-}
-
-export interface OutputNodeItem {
-  derived_summary?: OutputDerivedSummary;
-  fields: Record<string, string | string[]>;
-  id: string;
-  kind: 'node';
-  node_kind: string;
-  path?: string;
-  title: string;
-  visible_fields: OutputMetadataField[];
-}
-
-export interface OutputStoredQueryItem {
-  kind: 'stored_query';
-  name: string;
-  where: string;
-}
-
-export interface OutputResolvedLinkTarget {
-  derived_summary?: OutputDerivedSummary;
-  fields: Record<string, string | string[]>;
-  id: string;
-  kind: string;
-  path?: string;
-  title: string;
-  visible_fields: OutputMetadataField[];
-}
-
-export interface OutputResolvedLinkItem {
-  kind: 'resolved_link';
-  label: string;
-  reference: number;
-  target: OutputResolvedLinkTarget;
-}
-
-export interface QueryOutputView {
-  command: 'query';
-  hints: string[];
-  items: OutputNodeItem[];
-  summary: QueryOutputViewSummary;
-}
-
-export interface QueriesOutputView {
-  command: 'queries';
-  hints: string[];
-  items: OutputStoredQueryItem[];
-  summary: OutputViewSummary;
-}
-
-export interface ShowOutputView {
-  command: 'show';
-  document?: OutputNodeItem;
-  hints: string[];
-  items: OutputResolvedLinkItem[];
-  path: string;
-  rendered_source: string;
-  source: string;
-  summary: OutputViewSummary;
-}
-
-export type OutputView = QueryOutputView | QueriesOutputView | ShowOutputView;
-
-export interface ResolvedOutputMode {
-  color_enabled: boolean;
-  renderer_name: 'json' | 'plain' | 'rich';
-}

package/lib/overlay-graph.d.ts

@@ -1,43 +0,0 @@
-/**
- * @import { BuildGraphResult, GraphEdge, GraphNode } from './build-graph.types.ts';
- */
-/**
- * @typedef {{
- *   document_node_ids?: BuildGraphResult['document_node_ids'],
- *   edges?: GraphEdge[],
- *   nodes?: GraphNode[] | Record<string, GraphNode>,
- * }} GraphOverlay
- */
-/**
- * Graph overlay composition.
- *
- * Composes transient nodes and edges onto an existing Patram graph while
- * preserving the graph shape expected by query and document resolution
- * helpers.
- *
- * Kind: graph
- * Status: active
- * Uses Term: ../docs/reference/terms/document.md
- * Uses Term: ../docs/reference/terms/graph.md
- * Tracked in: ../docs/plans/v0/package-graph-overlay-helper.md
- * Decided by: ../docs/decisions/package-graph-overlay-helper.md
- * @patram
- * @see {@link ./query-graph.js}
- * @see {@link ../docs/decisions/package-graph-overlay-helper.md}
- */
-/**
- * Compose additional nodes and edges onto a loaded Patram graph.
- *
- * @param {BuildGraphResult} base_graph
- * @param {GraphOverlay} [graph_overlay]
- * @returns {BuildGraphResult}
- */
-export function overlayGraph(base_graph: BuildGraphResult, graph_overlay?: GraphOverlay): BuildGraphResult;
-export type GraphOverlay = {
-    document_node_ids?: BuildGraphResult["document_node_ids"];
-    edges?: GraphEdge[];
-    nodes?: GraphNode[] | Record<string, GraphNode>;
-};
-import type { BuildGraphResult } from './build-graph.types.ts';
-import type { GraphEdge } from './build-graph.types.ts';
-import type { GraphNode } from './build-graph.types.ts';

package/lib/overlay-graph.js

@@ -1,191 +0,0 @@
-/**
- * @import { BuildGraphResult, GraphEdge, GraphNode } from './build-graph.types.ts';
- */
-
-/**
- * @typedef {{
- *   document_node_ids?: BuildGraphResult['document_node_ids'],
- *   edges?: GraphEdge[],
- *   nodes?: GraphNode[] | Record<string, GraphNode>,
- * }} GraphOverlay
- */
-
-/**
- * Graph overlay composition.
- *
- * Composes transient nodes and edges onto an existing Patram graph while
- * preserving the graph shape expected by query and document resolution
- * helpers.
- *
- * Kind: graph
- * Status: active
- * Uses Term: ../docs/reference/terms/document.md
- * Uses Term: ../docs/reference/terms/graph.md
- * Tracked in: ../docs/plans/v0/package-graph-overlay-helper.md
- * Decided by: ../docs/decisions/package-graph-overlay-helper.md
- * @patram
- * @see {@link ./query-graph.js}
- * @see {@link ../docs/decisions/package-graph-overlay-helper.md}
- */
-
-/**
- * Compose additional nodes and edges onto a loaded Patram graph.
- *
- * @param {BuildGraphResult} base_graph
- * @param {GraphOverlay} [graph_overlay]
- * @returns {BuildGraphResult}
- */
-export function overlayGraph(base_graph, graph_overlay = {}) {
-  const graph_nodes = cloneGraphNodes(base_graph.nodes);
-  const overlay_nodes = normalizeOverlayNodes(graph_overlay.nodes);
-
-  applyOverlayNodes(graph_nodes, overlay_nodes);
-
-  const graph = {
-    edges: [...base_graph.edges, ...(graph_overlay.edges ?? [])],
-    nodes: graph_nodes,
-  };
-  const document_node_ids = createDocumentNodeIds(
-    base_graph.document_node_ids,
-    graph_nodes,
-    graph_overlay.document_node_ids,
-  );
-
-  attachDocumentNodeAliases(graph.nodes, document_node_ids);
-  Object.defineProperty(graph, 'document_node_ids', {
-    configurable: false,
-    enumerable: false,
-    value: document_node_ids,
-    writable: false,
-  });
-
-  return graph;
-}
-
-/**
- * @param {BuildGraphResult['nodes']} base_graph_nodes
- * @returns {BuildGraphResult['nodes']}
- */
-function cloneGraphNodes(base_graph_nodes) {
-  return Object.fromEntries(
-    Object.entries(base_graph_nodes).map(([node_id, graph_node]) => [
-      node_id,
-      { ...graph_node },
-    ]),
-  );
-}
-
-/**
- * @param {GraphOverlay['nodes']} overlay_nodes
- * @returns {GraphNode[]}
- */
-function normalizeOverlayNodes(overlay_nodes) {
-  if (!overlay_nodes) {
-    return [];
-  }
-
-  if (Array.isArray(overlay_nodes)) {
-    return overlay_nodes.map((graph_node) =>
-      normalizeOverlayNode(undefined, graph_node),
-    );
-  }
-
-  return Object.entries(overlay_nodes).map(([node_id, graph_node]) =>
-    normalizeOverlayNode(node_id, graph_node),
-  );
-}
-
-/**
- * @param {string | undefined} node_id
- * @param {GraphNode} graph_node
- * @returns {GraphNode}
- */
-function normalizeOverlayNode(node_id, graph_node) {
-  if (node_id === undefined) {
-    if (typeof graph_node.id !== 'string' || graph_node.id.length === 0) {
-      throw new Error('Overlay nodes must define an id.');
-    }
-
-    return { ...graph_node };
-  }
-
-  if (graph_node.id !== undefined && graph_node.id !== node_id) {
-    throw new Error(
-      `Overlay node "${node_id}" does not match embedded id "${graph_node.id}".`,
-    );
-  }
-
-  return {
-    ...graph_node,
-    id: node_id,
-  };
-}
-
-/**
- * @param {BuildGraphResult['nodes']} graph_nodes
- * @param {GraphNode[]} overlay_nodes
- */
-function applyOverlayNodes(graph_nodes, overlay_nodes) {
-  for (const overlay_node of overlay_nodes) {
-    const existing_node = graph_nodes[overlay_node.id];
-
-    graph_nodes[overlay_node.id] = existing_node
-      ? { ...existing_node, ...overlay_node }
-      : { ...overlay_node };
-  }
-}
-
-/**
- * @param {BuildGraphResult['document_node_ids']} base_document_node_ids
- * @param {BuildGraphResult['nodes']} graph_nodes
- * @param {BuildGraphResult['document_node_ids']} overlay_document_node_ids
- * @returns {Record<string, string>}
- */
-function createDocumentNodeIds(
-  base_document_node_ids,
-  graph_nodes,
-  overlay_document_node_ids,
-) {
-  /** @type {Record<string, string>} */
-  const document_node_ids = {
-    ...(base_document_node_ids ?? {}),
-  };
-
-  for (const graph_node of Object.values(graph_nodes)) {
-    if (!graph_node.$path) {
-      continue;
-    }
-
-    document_node_ids[graph_node.$path] = graph_node.id;
-  }
-
-  return {
-    ...document_node_ids,
-    ...(overlay_document_node_ids ?? {}),
-  };
-}
-
-/**
- * @param {BuildGraphResult['nodes']} graph_nodes
- * @param {Record<string, string>} document_node_ids
- */
-function attachDocumentNodeAliases(graph_nodes, document_node_ids) {
-  for (const [document_path, node_id] of Object.entries(document_node_ids)) {
-    if (`doc:${document_path}` === node_id) {
-      continue;
-    }
-
-    const graph_node = graph_nodes[node_id];
-
-    if (!graph_node) {
-      continue;
-    }
-
-    Object.defineProperty(graph_nodes, `doc:${document_path}`, {
-      configurable: false,
-      enumerable: false,
-      value: graph_node,
-      writable: false,
-    });
-  }
-}

package/lib/parse-claims.types.ts

@@ -1,41 +0,0 @@
-import type { PatramDiagnostic } from './load-patram-config.types.ts';
-
-export type MarkdownDirectiveStyle =
-  | 'front_matter'
-  | 'visible_line'
-  | 'list_item'
-  | 'hidden_tag';
-
-export interface ParseClaimsInput {
-  path: string;
-  source: string;
-}
-
-export interface ClaimOrigin {
-  path: string;
-  line: number;
-  column: number;
-}
-
-export interface PatramClaim {
-  document_id: string;
-  id: string;
-  markdown_style?: MarkdownDirectiveStyle;
-  name?: string;
-  origin: ClaimOrigin;
-  parser?: string;
-  type: string;
-  value: string | { target: string; text: string };
-}
-
-export type PatramClaimFields = Omit<
-  PatramClaim,
-  'document_id' | 'id' | 'origin' | 'type'
-> & {
-  origin?: ClaimOrigin;
-};
-
-export interface ParseSourceFileResult {
-  claims: PatramClaim[];
-  diagnostics: PatramDiagnostic[];
-}

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

@@ -1,69 +0,0 @@
-export type CliCommandName = 'check' | 'fields' | 'query' | 'queries' | 'show';
-export type CliHelpTopicName = 'query-language';
-export type CliHelpTargetKind = 'root' | 'command' | 'topic';
-
-export type CliOutputMode = 'default' | 'plain' | 'json';
-
-export type CliColorMode = 'auto' | 'always' | 'never';
-
-export interface ParsedCliCommandRequest {
-  kind?: 'command';
-  color_mode: CliColorMode;
-  command_arguments: string[];
-  command_name: CliCommandName;
-  output_mode: CliOutputMode;
-  query_inspection_mode?: 'explain' | 'lint';
-  query_limit?: number;
-  query_offset?: number;
-}
-
-export interface ParsedCliHelpRequest {
-  kind: 'help';
-  target_kind: CliHelpTargetKind;
-  target_name?: CliCommandName | CliHelpTopicName;
-}
-
-export type ParsedCliArguments = ParsedCliCommandRequest;
-export type ParsedCliRequest = ParsedCliCommandRequest | ParsedCliHelpRequest;
-
-export type CliParseError =
-  | {
-      code: 'message';
-      message: string;
-    }
-  | {
-      code: 'missing_required_argument';
-      argument_label: string;
-      command_name: 'query' | 'show';
-    }
-  | {
-      code: 'option_not_valid_for_command';
-      command_name: CliCommandName;
-      token: string;
-    }
-  | {
-      code: 'unknown_command';
-      suggestion?: CliCommandName;
-      token: string;
-    }
-  | {
-      code: 'unknown_help_target';
-      suggestion?: CliCommandName | CliHelpTopicName;
-      token: string;
-    }
-  | {
-      code: 'unknown_option';
-      command_name?: CliCommandName;
-      suggestion?: string;
-      token: string;
-    };
-
-export type ParseCliArgumentsResult =
-  | {
-      success: true;
-      value: ParsedCliRequest;
-    }
-  | {
-      error: CliParseError;
-      success: false;
-    };