patram 0.6.2 → 0.7.0

package/lib/query-graph.js

@@ -43,6 +43,14 @@ export const DEFAULT_QUERY_LIMIT = 25;
  * }} RelationIndexes
  */
 
+/**
+ * @typedef {{
+ *   bindings?: Record<string, string>,
+ *   limit?: number,
+ *   offset?: number,
+ * }} QueryGraphOptions
+ */
+
 /**
  * @typedef {{
  *   nodes: BuildGraphResult['nodes'],
@@ -55,17 +63,21 @@ export const DEFAULT_QUERY_LIMIT = 25;
  *
  * @param {BuildGraphResult} graph
  * @param {string} where_clause
- * @param {PatramRepoConfig | { limit?: number, offset?: number }=} repo_config_or_pagination
- * @param {{ limit?: number, offset?: number }=} pagination_options
+ * @param {PatramRepoConfig | QueryGraphOptions=} repo_config_or_query_options
+ * @param {QueryGraphOptions=} query_options
  * @returns {{ diagnostics: PatramDiagnostic[], nodes: GraphNode[], total_count: number }}
  */
 export function queryGraph(
   graph,
   where_clause,
-  repo_config_or_pagination = {},
-  pagination_options = {},
+  repo_config_or_query_options = {},
+  query_options = {},
 ) {
-  const parse_result = parseWhereClause(where_clause);
+  const { query_options: resolved_query_options, repo_config } =
+    resolveQueryGraphOptions(repo_config_or_query_options, query_options);
+  const parse_result = parseWhereClause(where_clause, {
+    bindings: resolved_query_options.bindings,
+  });
 
   if (!parse_result.success) {
     return {
@@ -75,9 +87,6 @@ export function queryGraph(
     };
   }
 
-  const { pagination_options: resolved_pagination_options, repo_config } =
-    resolveQueryGraphOptions(repo_config_or_pagination, pagination_options);
-
   if (repo_config) {
     const diagnostics = getQuerySemanticDiagnostics(
       repo_config,
@@ -102,10 +111,7 @@ export function queryGraph(
   const matching_nodes = graph_nodes.filter((graph_node) =>
     matchesExpression(graph_node, parse_result.expression, evaluation_context),
   );
-  const paginated_nodes = paginateNodes(
-    matching_nodes,
-    resolved_pagination_options,
-  );
+  const paginated_nodes = paginateNodes(matching_nodes, resolved_query_options);
 
   return {
     diagnostics: [],
@@ -501,29 +507,26 @@ function getScalarFieldValue(field_value) {
 }
 
 /**
- * @param {PatramRepoConfig | { limit?: number, offset?: number }} repo_config_or_pagination
- * @param {{ limit?: number, offset?: number }} pagination_options
- * @returns {{ pagination_options: { limit?: number, offset?: number }, repo_config: PatramRepoConfig | null }}
+ * @param {PatramRepoConfig | QueryGraphOptions} repo_config_or_query_options
+ * @param {QueryGraphOptions} query_options
+ * @returns {{ query_options: QueryGraphOptions, repo_config: PatramRepoConfig | null }}
  */
-function resolveQueryGraphOptions(
-  repo_config_or_pagination,
-  pagination_options,
-) {
-  if (isRepoConfig(repo_config_or_pagination)) {
+function resolveQueryGraphOptions(repo_config_or_query_options, query_options) {
+  if (isRepoConfig(repo_config_or_query_options)) {
     return {
-      pagination_options,
-      repo_config: repo_config_or_pagination,
+      query_options,
+      repo_config: repo_config_or_query_options,
     };
   }
 
   return {
-    pagination_options: repo_config_or_pagination,
+    query_options: repo_config_or_query_options,
     repo_config: null,
   };
 }
 
 /**
- * @param {PatramRepoConfig | { limit?: number, offset?: number }} value
+ * @param {PatramRepoConfig | QueryGraphOptions} value
  * @returns {value is PatramRepoConfig}
  */
 function isRepoConfig(value) {

package/lib/query-inspection.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @typedef {{ kind: 'ad_hoc' } | { kind: 'stored_query', name: string }} QuerySource
+ */
+/**
+ * @typedef {import('./parse-where-clause.types.ts').ParsedFieldTerm | import('./parse-where-clause.types.ts').ParsedFieldSetTerm} FieldDiagnosticTerm
+ */
+/**
+ * @typedef {{ query_source: QuerySource, where_clause: string }} ResolvedWhereClause
+ */
+/**
+ * @typedef {{ inspection_mode: 'explain' | 'lint', limit: number | null, offset: number }} QueryInspectionOptions
+ */
+/**
+ * @typedef {{
+ *   execution?: {
+ *     limit: number | null,
+ *     offset: number,
+ *   },
+ *   expression?: ParsedExpression,
+ *   inspection_mode: 'explain' | 'lint',
+ *   query_source: QuerySource,
+ *   where_clause: string,
+ * }} QueryInspectionSuccess
+ */
+/**
+ * Inspect one resolved query without executing it.
+ *
+ * @param {PatramRepoConfig} repo_config
+ * @param {ResolvedWhereClause} resolved_where_clause
+ * @param {QueryInspectionOptions} inspection_options
+ * @returns {{ success: true, value: QueryInspectionSuccess } | { diagnostics: PatramDiagnostic[], success: false }}
+ */
+export function inspectQuery(repo_config: PatramRepoConfig, resolved_where_clause: ResolvedWhereClause, inspection_options: QueryInspectionOptions): {
+    success: true;
+    value: QueryInspectionSuccess;
+} | {
+    diagnostics: PatramDiagnostic[];
+    success: false;
+};
+/**
+ * Render a successful query inspection in one output mode.
+ *
+ * @param {QueryInspectionSuccess} query_inspection
+ * @param {ResolvedOutputMode} output_mode
+ * @returns {string}
+ */
+export function renderQueryInspection(query_inspection: QueryInspectionSuccess, output_mode: ResolvedOutputMode): string;
+/**
+ * Collect schema-aware diagnostics for one parsed where clause.
+ *
+ * @param {PatramRepoConfig} repo_config
+ * @param {QuerySource} query_source
+ * @param {ParsedExpression} expression
+ * @returns {PatramDiagnostic[]}
+ */
+export function getQuerySemanticDiagnostics(repo_config: PatramRepoConfig, query_source: QuerySource, expression: ParsedExpression): PatramDiagnostic[];
+export type QuerySource = {
+    kind: "ad_hoc";
+} | {
+    kind: "stored_query";
+    name: string;
+};
+export type FieldDiagnosticTerm = import("./parse-where-clause.types.ts").ParsedFieldTerm | import("./parse-where-clause.types.ts").ParsedFieldSetTerm;
+export type ResolvedWhereClause = {
+    query_source: QuerySource;
+    where_clause: string;
+};
+export type QueryInspectionOptions = {
+    inspection_mode: "explain" | "lint";
+    limit: number | null;
+    offset: number;
+};
+export type QueryInspectionSuccess = {
+    execution?: {
+        limit: number | null;
+        offset: number;
+    };
+    expression?: ParsedExpression;
+    inspection_mode: "explain" | "lint";
+    query_source: QuerySource;
+    where_clause: string;
+};
+import type { PatramRepoConfig } from './load-patram-config.types.ts';
+import type { PatramDiagnostic } from './load-patram-config.types.ts';
+import type { ResolvedOutputMode } from './output-view.types.ts';
+import type { ParsedExpression } from './parse-where-clause.types.ts';

package/lib/resolve-patram-graph-config.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Merge built-in Patram graph semantics with repo-defined schema.
+ *
+ * @param {PatramRepoConfig} repo_config
+ * @returns {PatramConfig}
+ */
+export function resolvePatramGraphConfig(repo_config: PatramRepoConfig): PatramConfig;
+import type { PatramRepoConfig } from './load-patram-config.types.ts';
+import type { PatramConfig } from './patram-config.types.ts';

package/lib/source-file-defaults.d.ts

@@ -0,0 +1,5 @@
+export const MARKDOWN_SOURCE_FILE_EXTENSIONS: string[];
+export const YAML_SOURCE_FILE_EXTENSIONS: string[];
+export const JSDOC_SOURCE_FILE_EXTENSIONS: string[];
+export const SUPPORTED_SOURCE_FILE_EXTENSIONS: string[];
+export const DEFAULT_INCLUDE_PATTERNS: string[];

package/lib/tagged-fenced-block-error.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @import { TaggedFencedBlockError } from './tagged-fenced-blocks.types.ts';
+ */
+/**
+ * @param {string} code
+ * @param {string} message
+ * @returns {TaggedFencedBlockError}
+ */
+export function createTaggedFencedBlockError(code: string, message: string): TaggedFencedBlockError;
+import type { TaggedFencedBlockError } from './tagged-fenced-blocks.types.ts';

package/lib/tagged-fenced-block-markdown.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @param {string[]} lines
+ * @returns {number}
+ */
+export function findMarkdownBodyStartLineIndex(lines: string[]): number;
+/**
+ * @param {string[]} lines
+ * @param {number} body_start
+ * @returns {string}
+ */
+export function getMarkdownTitle(lines: string[], body_start: number): string;
+/**
+ * @param {string} line
+ * @returns {{ level: number, text: string } | null}
+ */
+export function parseHeading(line: string): {
+    level: number;
+    text: string;
+} | null;
+/**
+ * @param {string[]} heading_path
+ * @param {string} title
+ * @param {{ level: number, text: string }} heading
+ * @returns {string[]}
+ */
+export function updateHeadingPath(heading_path: string[], title: string, heading: {
+    level: number;
+    text: string;
+}): string[];
+/**
+ * @param {string} line
+ * @returns {{ character: string, lang: string, length: number } | null}
+ */
+export function parseOpeningMarkdownFence(line: string): {
+    character: string;
+    lang: string;
+    length: number;
+} | null;
+/**
+ * @param {string} line
+ * @param {{ character: string, length: number }} open_fence
+ * @returns {boolean}
+ */
+export function isClosingMarkdownFence(line: string, open_fence: {
+    character: string;
+    length: number;
+}): boolean;

package/lib/tagged-fenced-block-metadata.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @param {string} file_path
+ * @param {{ metadata: Record<string, string>, tag_lines: number[] }} pending_tag_set
+ * @param {{ metadata: Record<string, string>, tag_lines: number[] }} next_tag_set
+ * @returns {{ metadata: Record<string, string>, tag_lines: number[] }}
+ */
+export function mergePendingTagSets(file_path: string, pending_tag_set: {
+    metadata: Record<string, string>;
+    tag_lines: number[];
+}, next_tag_set: {
+    metadata: Record<string, string>;
+    tag_lines: number[];
+}): {
+    metadata: Record<string, string>;
+    tag_lines: number[];
+};
+/**
+ * @param {string} file_path
+ * @param {string} line
+ * @param {number} line_number
+ * @returns {{ metadata: Record<string, string>, tag_lines: number[] } | null}
+ */
+export function parseTaggedMetadataLine(file_path: string, line: string, line_number: number): {
+    metadata: Record<string, string>;
+    tag_lines: number[];
+} | null;

package/lib/tagged-fenced-block-parser.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @typedef {{ metadata: Record<string, string>, tag_lines: number[] }} PendingTagSet
+ */
+/**
+ * @typedef {{
+ *   heading_path: string[];
+ *   lang: string;
+ *   line_start: number;
+ *   metadata: Record<string, string>;
+ *   tag_lines: number[];
+ *   value_lines: string[];
+ * }} OpenTaggedBlock
+ */
+/**
+ * @typedef {{ character: string, lang: string, length: number }} OpenFence
+ */
+/**
+ * @typedef {{
+ *   blocks: TaggedFencedBlock[];
+ *   body_start: number;
+ *   heading_path: string[];
+ *   open_fence: OpenFence | null;
+ *   open_tagged_block: OpenTaggedBlock | null;
+ *   pending_tag_set: PendingTagSet | null;
+ *   title: string;
+ * }} TaggedBlockScannerState
+ */
+/**
+ * @param {TaggedFencedBlocksInput} input
+ * @returns {TaggedFencedBlockFile}
+ */
+export function extractTaggedFencedBlocksFromSource(input: TaggedFencedBlocksInput): TaggedFencedBlockFile;
+export type PendingTagSet = {
+    metadata: Record<string, string>;
+    tag_lines: number[];
+};
+export type OpenTaggedBlock = {
+    heading_path: string[];
+    lang: string;
+    line_start: number;
+    metadata: Record<string, string>;
+    tag_lines: number[];
+    value_lines: string[];
+};
+export type OpenFence = {
+    character: string;
+    lang: string;
+    length: number;
+};
+export type TaggedBlockScannerState = {
+    blocks: TaggedFencedBlock[];
+    body_start: number;
+    heading_path: string[];
+    open_fence: OpenFence | null;
+    open_tagged_block: OpenTaggedBlock | null;
+    pending_tag_set: PendingTagSet | null;
+    title: string;
+};
+import type { TaggedFencedBlocksInput } from './tagged-fenced-blocks.types.ts';
+import type { TaggedFencedBlockFile } from './tagged-fenced-blocks.types.ts';
+import type { TaggedFencedBlock } from './tagged-fenced-blocks.types.ts';

package/lib/tagged-fenced-blocks.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Tagged fenced block public API.
+ *
+ * Loads or extracts one markdown file worth of tagged fenced blocks and
+ * provides exact-match selection helpers.
+ *
+ * Kind: parse
+ * Status: active
+ * Tracked in: ../docs/plans/v0/tagged-fenced-block-extraction.md
+ * Decided by: ../docs/decisions/tagged-fenced-block-extraction.md
+ * @patram
+ * @see {@link ../docs/decisions/tagged-fenced-block-extraction.md}
+ */
+/**
+ * @param {TaggedFencedBlocksInput} input
+ * @returns {TaggedFencedBlockFile}
+ */
+export function extractTaggedFencedBlocks(input: TaggedFencedBlocksInput): TaggedFencedBlockFile;
+/**
+ * @param {string} file_path
+ * @returns {Promise<TaggedFencedBlockFile>}
+ */
+export function loadTaggedFencedBlocks(file_path: string): Promise<TaggedFencedBlockFile>;
+/**
+ * @param {TaggedFencedBlock[]} blocks
+ * @param {TaggedFencedBlockCriteria} criteria
+ * @returns {TaggedFencedBlock[]}
+ */
+export function selectTaggedBlocks(blocks: TaggedFencedBlock[], criteria: TaggedFencedBlockCriteria): TaggedFencedBlock[];
+/**
+ * @param {TaggedFencedBlock[]} blocks
+ * @param {TaggedFencedBlockCriteria} criteria
+ * @returns {TaggedFencedBlock}
+ */
+export function selectTaggedBlock(blocks: TaggedFencedBlock[], criteria: TaggedFencedBlockCriteria): TaggedFencedBlock;
+import type { TaggedFencedBlocksInput } from './tagged-fenced-blocks.types.ts';
+import type { TaggedFencedBlockFile } from './tagged-fenced-blocks.types.ts';
+import type { TaggedFencedBlock } from './tagged-fenced-blocks.types.ts';
+import type { TaggedFencedBlockCriteria } from './tagged-fenced-blocks.types.ts';

package/lib/tagged-fenced-blocks.types.d.ts

@@ -0,0 +1,32 @@
+export interface TaggedFencedBlocksInput {
+    file_path: string;
+    source_text: string;
+}
+export interface TaggedFencedBlockCriteria {
+    [key: string]: string;
+}
+export interface TaggedFencedBlockOrigin {
+    path: string;
+    line_start: number;
+    line_end: number;
+    tag_lines: number[];
+}
+export interface TaggedFencedBlockContext {
+    heading_path: string[];
+}
+export interface TaggedFencedBlock {
+    id: string;
+    lang: string;
+    value: string;
+    metadata: Record<string, string>;
+    origin: TaggedFencedBlockOrigin;
+    context: TaggedFencedBlockContext;
+}
+export interface TaggedFencedBlockFile {
+    path: string;
+    title: string;
+    blocks: TaggedFencedBlock[];
+}
+export interface TaggedFencedBlockError extends Error {
+    code: string;
+}

package/package.json

@@ -1,18 +1,27 @@
 {
   "name": "patram",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "type": "module",
   "main": "./lib/patram.js",
+  "types": "./lib/patram.d.ts",
   "exports": {
-    ".": "./lib/patram.js",
+    ".": {
+      "types": "./lib/patram.d.ts",
+      "default": "./lib/patram.js"
+    },
     "./bin/patram.js": "./bin/patram.js"
   },
   "files": [
     "bin/patram.js",
+    "lib/**/*.d.ts",
     "lib/**/*.js",
     "lib/**/*.ts",
+    "!bin/**/*.test.d.ts",
+    "!bin/**/*.test-helpers.d.ts",
     "!bin/**/*.test.js",
     "!bin/**/*.test-helpers.js",
+    "!lib/**/*.test.d.ts",
+    "!lib/**/*.test-helpers.d.ts",
     "!lib/**/*.test.js",
     "!lib/**/*.test-helpers.js"
   ],
@@ -37,6 +46,8 @@
     "check:staged": "lint-staged",
     "check:types": "tsc",
     "postversion": "git push && git push --tags",
+    "postpack": "node scripts/clean-package-api-declarations.js",
+    "prepack": "node scripts/build-package-api-declarations.js",
     "preversion": "npm run all",
     "prepare": "husky",
     "test": "vitest run",