patram 0.0.2 → 0.1.1

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

@@ -1,10 +1,19 @@
+import type {
+  KindDefinition,
+  MappingDefinition,
+  RelationDefinition,
+} from './patram-config.types.ts';
+
 export interface StoredQueryConfig {
   where: string;
 }
 
 export interface PatramRepoConfig {
   include: string[];
+  kinds?: Record<string, KindDefinition>;
+  mappings?: Record<string, MappingDefinition>;
   queries: Record<string, StoredQueryConfig>;
+  relations?: Record<string, RelationDefinition>;
 }
 
 export interface PatramDiagnostic {

package/lib/load-project-graph.js

@@ -0,0 +1,124 @@
+/**
+ * @import { BuildGraphResult } from './build-graph.types.ts';
+ * @import { PatramClaim } from './parse-claims.types.ts';
+ * @import { PatramDiagnostic, PatramRepoConfig } from './load-patram-config.types.ts';
+ */
+
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import { buildGraph } from './build-graph.js';
+import { listSourceFiles } from './list-source-files.js';
+import { loadPatramConfig } from './load-patram-config.js';
+import { parseSourceFile } from './parse-claims.js';
+import { resolvePatramGraphConfig } from './resolve-patram-graph-config.js';
+
+/**
+ * Project graph loading pipeline.
+ *
+ * Loads config, scans source files, parses claims, and materializes the graph
+ * used by CLI commands.
+ *
+ * Kind: graph
+ * Status: active
+ * Uses Term: ../docs/reference/terms/claim.md
+ * Uses Term: ../docs/reference/terms/graph.md
+ * Uses Term: ../docs/reference/terms/mapping.md
+ * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../docs/decisions/dogfood-query-graph-v0.md
+ * @patram
+ * @see {@link ./parse-claims.js}
+ * @see {@link ./build-graph.js}
+ */
+
+/**
+ * Load config, source files, claims, and the materialized graph for one
+ * project directory.
+ *
+ * @param {string} project_directory
+ * @returns {Promise<{ config: PatramRepoConfig, diagnostics: PatramDiagnostic[], graph: BuildGraphResult, source_file_paths: string[] }>}
+ */
+export async function loadProjectGraph(project_directory) {
+  const load_result = await loadPatramConfig(project_directory);
+
+  if (load_result.diagnostics.length > 0) {
+    return {
+      config: {
+        include: [],
+        queries: {},
+      },
+      diagnostics: load_result.diagnostics,
+      graph: {
+        edges: [],
+        nodes: {},
+      },
+      source_file_paths: [],
+    };
+  }
+
+  const repo_config = load_result.config;
+
+  if (!repo_config) {
+    throw new Error('Expected a valid Patram repo config.');
+  }
+
+  const source_file_paths = await listSourceFiles(
+    repo_config.include,
+    project_directory,
+  );
+  const collect_result = await collectClaims(
+    source_file_paths,
+    project_directory,
+  );
+  const graph_config = resolvePatramGraphConfig(repo_config);
+
+  if (collect_result.diagnostics.length > 0) {
+    return {
+      config: repo_config,
+      diagnostics: collect_result.diagnostics,
+      graph: {
+        edges: [],
+        nodes: {},
+      },
+      source_file_paths,
+    };
+  }
+
+  return {
+    config: repo_config,
+    diagnostics: [],
+    graph: buildGraph(graph_config, collect_result.claims),
+    source_file_paths,
+  };
+}
+
+/**
+ * @param {string[]} source_file_paths
+ * @param {string} project_directory
+ * @returns {Promise<{ claims: PatramClaim[], diagnostics: PatramDiagnostic[] }>}
+ */
+async function collectClaims(source_file_paths, project_directory) {
+  /** @type {PatramClaim[]} */
+  const claims = [];
+  /** @type {PatramDiagnostic[]} */
+  const diagnostics = [];
+
+  for (const source_file_path of source_file_paths) {
+    const source_text = await readFile(
+      resolve(project_directory, source_file_path),
+      'utf8',
+    );
+    const parse_result = parseSourceFile({
+      path: source_file_path,
+      source: source_text,
+    });
+
+    claims.push(...parse_result.claims);
+    diagnostics.push(...parse_result.diagnostics);
+  }
+
+  return {
+    claims,
+    diagnostics,
+  };
+}

package/lib/output-view.types.ts

@@ -0,0 +1,73 @@
+import type { GraphNode } from './build-graph.types.ts';
+
+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 {
+  id: string;
+  kind: 'node';
+  node_kind: GraphNode['kind'];
+  path: string;
+  status?: string;
+  title: string;
+}
+
+export interface OutputStoredQueryItem {
+  kind: 'stored_query';
+  name: string;
+  where: string;
+}
+
+export interface OutputResolvedLinkTarget {
+  kind?: string;
+  path: string;
+  status?: string;
+  title: string;
+}
+
+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';
+  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/parse-claims.js

@@ -1,178 +1,58 @@
+/** @import * as $k$$l$parse$j$claims$k$types$k$ts from './parse-claims.types.ts'; */
 /**
- * @import { PatramClaim, ParseClaimsInput, PatramClaimFields } from './parse-claims.types.ts';
+ * @import { ParseClaimsInput, ParseSourceFileResult } from './parse-claims.types.ts';
  */
 
-const MARKDOWN_EXTENSIONS = new Set(['.md', '.markdown']);
-const MARKDOWN_LINK_PATTERN = /\[([^\]]+)\]\(([^)]+)\)/dgu;
-const DIRECTIVE_PATTERN = /^([A-Z][A-Za-z ]+):\s+(.+)$/du;
-const HEADING_PATTERN = /^#\s+(.+)$/du;
+import { getFileExtension } from './claim-helpers.js';
+import { parseJsdocClaims } from './parse-jsdoc-claims.js';
+import { parseMarkdownClaims } from './parse-markdown-claims.js';
+import { MARKDOWN_SOURCE_FILE_EXTENSIONS } from './source-file-defaults.js';
 
 /**
- * Parse a file into neutral Patram claims.
+ * Source claim dispatch.
  *
- * @param {ParseClaimsInput} parse_input
- * @returns {PatramClaim[]}
+ * Routes each source file to markdown or JSDoc claim parsing and keeps claim
+ * extraction on one entrypoint.
+ *
+ * Kind: parse
+ * Status: active
+ * Uses Term: ../docs/reference/terms/claim.md
+ * Uses Term: ../docs/reference/terms/document.md
+ * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../docs/decisions/jsdoc-metadata-directive-syntax.md
+ * Implements: ../docs/tasks/v0/parse-claims.md
+ * @patram
+ * @see {@link ./parse-markdown-claims.js}
+ * @see {@link ./parse-jsdoc-claims.js}
  */
-export function parseClaims(parse_input) {
-  const file_extension = getFileExtension(parse_input.path);
-
-  if (MARKDOWN_EXTENSIONS.has(file_extension)) {
-    return parseMarkdownClaims(parse_input);
-  }
 
-  return [];
-}
+const MARKDOWN_EXTENSIONS = new Set(MARKDOWN_SOURCE_FILE_EXTENSIONS);
 
 /**
+ * Parse one source file into claims and diagnostics.
+ *
  * @param {ParseClaimsInput} parse_input
- * @returns {PatramClaim[]}
- */
-function parseMarkdownClaims(parse_input) {
-  const lines = parse_input.source.split('\n');
-
-  /** @type {PatramClaim[]} */
-  const claims = [];
-  const title_value = getMarkdownTitle(lines);
-
-  if (title_value) {
-    claims.push(
-      createClaim(parse_input.path, claims.length + 1, 'document.title', {
-        value: title_value,
-      }),
-    );
-  }
-
-  for (const [line_index, line] of lines.entries()) {
-    const line_number = line_index + 1;
-
-    collectMarkdownLinkClaims(parse_input.path, line, line_number, claims);
-    collectDirectiveClaims(parse_input.path, line, line_number, claims);
-  }
-
-  return claims;
-}
-
-/**
- * @param {string} file_path
- * @param {string} line
- * @param {number} line_number
- * @param {PatramClaim[]} claims
- */
-function collectMarkdownLinkClaims(file_path, line, line_number, claims) {
-  for (const link_match of line.matchAll(MARKDOWN_LINK_PATTERN)) {
-    const link_text = link_match[1];
-    const target_value = link_match[2];
-    const column_number =
-      link_match.index === undefined ? 1 : link_match.index + 1;
-
-    claims.push(
-      createClaim(file_path, claims.length + 1, 'markdown.link', {
-        origin: {
-          column: column_number,
-          line: line_number,
-          path: file_path,
-        },
-        value: {
-          target: target_value,
-          text: link_text,
-        },
-      }),
-    );
-  }
-}
-
-/**
- * @param {string} file_path
- * @param {string} line
- * @param {number} line_number
- * @param {PatramClaim[]} claims
- */
-function collectDirectiveClaims(file_path, line, line_number, claims) {
-  const directive_match = line.match(DIRECTIVE_PATTERN);
-
-  if (!directive_match) {
-    return;
-  }
-
-  const directive_name = normalizeDirectiveName(directive_match[1]);
-  const directive_value = directive_match[2].trim();
-
-  claims.push(
-    createClaim(file_path, claims.length + 1, 'directive', {
-      name: directive_name,
-      origin: {
-        column: 1,
-        line: line_number,
-        path: file_path,
-      },
-      parser: 'markdown',
-      value: directive_value,
-    }),
-  );
-}
-
-/**
- * @param {string[]} lines
- * @returns {string | null}
+ * @returns {ParseSourceFileResult}
  */
-function getMarkdownTitle(lines) {
-  const first_line = lines[0].trim();
-
-  if (first_line.length === 0) {
-    return null;
-  }
-
-  const heading_match = first_line.match(HEADING_PATTERN);
+export function parseSourceFile(parse_input) {
+  const file_extension = getFileExtension(parse_input.path);
 
-  if (heading_match) {
-    return heading_match[1].trim();
+  if (MARKDOWN_EXTENSIONS.has(file_extension)) {
+    return {
+      claims: parseMarkdownClaims(parse_input),
+      diagnostics: [],
+    };
   }
 
-  return first_line;
-}
-
-/**
- * @param {string} file_path
- * @param {number} claim_number
- * @param {string} claim_type
- * @param {PatramClaimFields} claim_fields
- * @returns {PatramClaim}
- */
-function createClaim(file_path, claim_number, claim_type, claim_fields) {
-  const document_id = `doc:${file_path}`;
-  const origin = claim_fields.origin ?? {
-    column: 1,
-    line: 1,
-    path: file_path,
-  };
-
-  return {
-    ...claim_fields,
-    document_id,
-    id: `claim:${document_id}:${claim_number}`,
-    origin,
-    type: claim_type,
-  };
-}
-
-/**
- * @param {string} directive_label
- * @returns {string}
- */
-function normalizeDirectiveName(directive_label) {
-  return directive_label.trim().toLowerCase().replaceAll(/\s+/dgu, '_');
+  return parseJsdocClaims(parse_input);
 }
 
 /**
- * @param {string} file_path
- * @returns {string}
+ * Parse a file into neutral Patram claims.
+ *
+ * @param {ParseClaimsInput} parse_input
+ * @returns {$k$$l$parse$j$claims$k$types$k$ts.PatramClaim[]}
  */
-function getFileExtension(file_path) {
-  const last_dot_index = file_path.lastIndexOf('.');
-
-  if (last_dot_index < 0) {
-    return '';
-  }
-
-  return file_path.slice(last_dot_index);
+export function parseClaims(parse_input) {
+  return parseSourceFile(parse_input).claims;
 }

package/lib/parse-claims.types.ts

@@ -1,3 +1,5 @@
+import type { PatramDiagnostic } from './load-patram-config.types.ts';
+
 export interface ParseClaimsInput {
   path: string;
   source: string;
@@ -25,3 +27,8 @@ export type PatramClaimFields = Omit<
 > & {
   origin?: ClaimOrigin;
 };
+
+export interface ParseSourceFileResult {
+  claims: PatramClaim[];
+  diagnostics: PatramDiagnostic[];
+}