patram 0.0.2 → 0.1.1

package/lib/parse-markdown-directives.js

@@ -0,0 +1,136 @@
+/**
+ * @import { PatramClaimFields } from './parse-claims.types.ts';
+ */
+
+const FRONT_MATTER_BOUNDARY_PATTERN = /^---$/du;
+const FRONT_MATTER_DIRECTIVE_PATTERN = /^([A-Za-z][A-Za-z0-9 _-]*):\s+(.+)$/du;
+const MARKDOWN_HIDDEN_DIRECTIVE_PATTERN =
+  /^\[patram\s+([A-Za-z][A-Za-z0-9 _-]*)=(.+)\]:\s*#\s*$/du;
+const VISIBLE_DIRECTIVE_PATTERN = /^(?:-\s+)?([A-Z][A-Za-z _-]*):\s+(.+)$/du;
+
+/**
+ * @param {string} file_path
+ * @param {string[]} lines
+ * @returns {{ body_start: number, directive_fields: PatramClaimFields[] }}
+ */
+export function parseFrontMatterDirectiveFields(file_path, lines) {
+  if (lines[0] !== '---') {
+    return {
+      body_start: 0,
+      directive_fields: [],
+    };
+  }
+
+  const closing_line_index = findFrontMatterClosingLineIndex(lines);
+
+  if (closing_line_index < 0) {
+    return {
+      body_start: 0,
+      directive_fields: [],
+    };
+  }
+
+  /** @type {PatramClaimFields[]} */
+  const directive_fields = [];
+
+  for (let line_index = 1; line_index < closing_line_index; line_index += 1) {
+    const directive_fields_match = matchDirectiveFields(
+      FRONT_MATTER_DIRECTIVE_PATTERN,
+      file_path,
+      lines[line_index],
+      line_index + 1,
+    );
+
+    if (!directive_fields_match) {
+      continue;
+    }
+
+    directive_fields.push(directive_fields_match);
+  }
+
+  return {
+    body_start: closing_line_index + 1,
+    directive_fields,
+  };
+}
+
+/**
+ * @param {string} file_path
+ * @param {string} line
+ * @param {number} line_number
+ * @returns {PatramClaimFields | null}
+ */
+export function matchVisibleDirectiveFields(file_path, line, line_number) {
+  return matchDirectiveFields(
+    VISIBLE_DIRECTIVE_PATTERN,
+    file_path,
+    line,
+    line_number,
+  );
+}
+
+/**
+ * @param {string} file_path
+ * @param {string} line
+ * @param {number} line_number
+ * @returns {PatramClaimFields | null}
+ */
+export function matchHiddenDirectiveFields(file_path, line, line_number) {
+  return matchDirectiveFields(
+    MARKDOWN_HIDDEN_DIRECTIVE_PATTERN,
+    file_path,
+    line,
+    line_number,
+  );
+}
+
+/**
+ * @param {string[]} lines
+ * @returns {number}
+ */
+function findFrontMatterClosingLineIndex(lines) {
+  for (let line_index = 1; line_index < lines.length; line_index += 1) {
+    if (FRONT_MATTER_BOUNDARY_PATTERN.test(lines[line_index])) {
+      return line_index;
+    }
+  }
+
+  return -1;
+}
+
+/**
+ * @param {RegExp} pattern
+ * @param {string} file_path
+ * @param {string} line
+ * @param {number} line_number
+ * @returns {PatramClaimFields | null}
+ */
+function matchDirectiveFields(pattern, file_path, line, line_number) {
+  const directive_match = line.match(pattern);
+
+  if (!directive_match) {
+    return null;
+  }
+
+  return {
+    name: normalizeDirectiveName(directive_match[1]),
+    origin: {
+      column: 1,
+      line: line_number,
+      path: file_path,
+    },
+    parser: 'markdown',
+    value: directive_match[2].trim(),
+  };
+}
+
+/**
+ * @param {string} directive_label
+ * @returns {string}
+ */
+export function normalizeDirectiveName(directive_label) {
+  return directive_label
+    .trim()
+    .toLowerCase()
+    .replaceAll(/[\s-]+/dgu, '_');
+}

package/lib/parse-where-clause.js

@@ -0,0 +1,312 @@
+/**
+ * @import { PatramDiagnostic } from './load-patram-config.types.ts';
+ */
+
+/**
+ * @typedef {{
+ *   field_name: 'id' | 'kind' | 'path' | 'status' | 'title',
+ *   kind: 'field',
+ *   operator: '=' | '^=' | '~',
+ *   value: string,
+ * }} ParsedFieldTerm
+ */
+
+/**
+ * @typedef {{
+ *   kind: 'relation',
+ *   relation_name: string,
+ * }} ParsedRelationTerm
+ */
+
+/**
+ * @typedef {{
+ *   kind: 'relation_target',
+ *   relation_name: string,
+ *   target_id: string,
+ * }} ParsedRelationTargetTerm
+ */
+
+/**
+ * @typedef {{
+ *   is_negated: boolean,
+ *   term: ParsedFieldTerm | ParsedRelationTerm | ParsedRelationTargetTerm,
+ * }} ParsedClause
+ */
+
+/**
+ * @typedef {{
+ *   clause: ParsedClause,
+ *   success: true,
+ * } | {
+ *   diagnostic: PatramDiagnostic,
+ *   success: false,
+ * }} CreateClauseResult
+ */
+
+/**
+ * @typedef {{
+ *   clauses: ParsedClause[],
+ *   success: true,
+ * } | {
+ *   diagnostic: PatramDiagnostic,
+ *   success: false,
+ * }} ParseWhereClauseResult
+ */
+
+/**
+ * Parse one v0 where clause into structured clauses.
+ *
+ * @param {string} where_clause
+ * @returns {ParseWhereClauseResult}
+ */
+export function parseWhereClause(where_clause) {
+  const tokens = tokenizeWhereClause(where_clause);
+
+  if (tokens.length === 0) {
+    return {
+      diagnostic: createQueryDiagnostic(1, 'Query must not be empty.'),
+      success: false,
+    };
+  }
+
+  return parseTokens(tokens, where_clause);
+}
+
+/**
+ * @param {{ value: string, column: number }[]} tokens
+ * @param {string} where_clause
+ * @returns {ParseWhereClauseResult}
+ */
+function parseTokens(tokens, where_clause) {
+  /** @type {ParsedClause[]} */
+  const clauses = [];
+  let should_expect_term = true;
+  let is_negated = false;
+
+  for (const token of tokens) {
+    if (token.value === 'and') {
+      if (should_expect_term) {
+        return {
+          diagnostic: createQueryDiagnostic(
+            token.column,
+            `Unsupported query token "${token.value}".`,
+          ),
+          success: false,
+        };
+      }
+
+      should_expect_term = true;
+      continue;
+    }
+
+    if (!should_expect_term) {
+      return {
+        diagnostic: createQueryDiagnostic(
+          token.column,
+          `Unsupported query token "${token.value}".`,
+        ),
+        success: false,
+      };
+    }
+
+    if (token.value === 'not') {
+      is_negated = true;
+      continue;
+    }
+
+    const clause_result = createClause(token, is_negated);
+
+    if (!clause_result.success) {
+      return clause_result;
+    }
+
+    clauses.push(clause_result.clause);
+    is_negated = false;
+    should_expect_term = false;
+  }
+
+  if (should_expect_term) {
+    return {
+      diagnostic: createQueryDiagnostic(
+        where_clause.length + 1,
+        'Expected a query term.',
+      ),
+      success: false,
+    };
+  }
+
+  return {
+    clauses,
+    success: true,
+  };
+}
+
+/**
+ * @param {{ value: string, column: number }} token
+ * @param {boolean} is_negated
+ * @returns {CreateClauseResult}
+ */
+function createClause(token, is_negated) {
+  const field_term = createFieldTerm(token.value);
+
+  if (field_term) {
+    return {
+      clause: {
+        is_negated,
+        term: field_term,
+      },
+      success: true,
+    };
+  }
+
+  const relation_target_term = createRelationTargetTerm(token.value);
+
+  if (relation_target_term) {
+    return {
+      clause: {
+        is_negated,
+        term: relation_target_term,
+      },
+      success: true,
+    };
+  }
+
+  if (/^[a-z_]+:\*$/u.test(token.value)) {
+    return {
+      clause: {
+        is_negated,
+        term: {
+          kind: 'relation',
+          relation_name: token.value.slice(0, -2),
+        },
+      },
+      success: true,
+    };
+  }
+
+  return {
+    diagnostic: createQueryDiagnostic(
+      token.column,
+      `Unsupported query token "${token.value}".`,
+    ),
+    success: false,
+  };
+}
+
+/**
+ * @param {string} query_term
+ * @returns {ParsedFieldTerm | null}
+ */
+function createFieldTerm(query_term) {
+  if (query_term.startsWith('id=')) {
+    return {
+      field_name: 'id',
+      kind: 'field',
+      operator: '=',
+      value: query_term.slice('id='.length),
+    };
+  }
+
+  if (query_term.startsWith('id^=')) {
+    return {
+      field_name: 'id',
+      kind: 'field',
+      operator: '^=',
+      value: query_term.slice('id^='.length),
+    };
+  }
+
+  if (query_term.startsWith('kind=')) {
+    return {
+      field_name: 'kind',
+      kind: 'field',
+      operator: '=',
+      value: query_term.slice('kind='.length),
+    };
+  }
+
+  if (query_term.startsWith('status=')) {
+    return {
+      field_name: 'status',
+      kind: 'field',
+      operator: '=',
+      value: query_term.slice('status='.length),
+    };
+  }
+
+  if (query_term.startsWith('path=')) {
+    return {
+      field_name: 'path',
+      kind: 'field',
+      operator: '=',
+      value: query_term.slice('path='.length),
+    };
+  }
+
+  if (query_term.startsWith('path^=')) {
+    return {
+      field_name: 'path',
+      kind: 'field',
+      operator: '^=',
+      value: query_term.slice('path^='.length),
+    };
+  }
+
+  if (query_term.startsWith('title~')) {
+    return {
+      field_name: 'title',
+      kind: 'field',
+      operator: '~',
+      value: query_term.slice('title~'.length),
+    };
+  }
+
+  return null;
+}
+
+/**
+ * @param {string} query_term
+ * @returns {ParsedRelationTargetTerm | null}
+ */
+function createRelationTargetTerm(query_term) {
+  const relation_target_match = query_term.match(
+    /^(?<relation_name>[a-z_]+)=(?<target_id>[^\s=:]+:[^\s]+)$/u,
+  );
+
+  if (!relation_target_match?.groups) {
+    return null;
+  }
+
+  return {
+    kind: 'relation_target',
+    relation_name: relation_target_match.groups.relation_name,
+    target_id: relation_target_match.groups.target_id,
+  };
+}
+
+/**
+ * @param {number} column_number
+ * @param {string} message
+ * @returns {PatramDiagnostic}
+ */
+function createQueryDiagnostic(column_number, message) {
+  return {
+    code: 'query.invalid',
+    column: column_number,
+    level: 'error',
+    line: 1,
+    message,
+    path: '<query>',
+  };
+}
+
+/**
+ * @param {string} where_clause
+ * @returns {{ value: string, column: number }[]}
+ */
+function tokenizeWhereClause(where_clause) {
+  return [...where_clause.matchAll(/\S+/gu)].map((token_match) => ({
+    column: (token_match.index ?? 0) + 1,
+    value: token_match[0],
+  }));
+}