@simtlix/simfinity-js 2.4.4 → 2.5.0

package/.cursor/rules/simfinity-core-functions.mdc

@@ -55,11 +55,13 @@ Handles: scalars, enums, relation fields (`IdInputType` for refs, nested input f
 `buildQuery(args, gqltype)` translates GraphQL filter arguments into a MongoDB aggregation pipeline:
 
 - `buildQueryTerms()` -- converts scalar/enum filters to `$match`, object/relation filters to `$lookup` + `$unwind` + `$match`
+- `buildFilterGroupMatch()` -- recursively processes `QLFilterGroup` (AND/OR) into nested MongoDB `$and`/`$or` match expressions. Reuses `buildQueryTerms()` for each leaf condition. Deduplicates `$lookup` stages via shared `aggregationsIncluded` dict. Max depth: 5.
 - `buildAggregationsForSort()` -- adds `$lookup`/`$unwind` for sort on related fields
 - Pagination: `$skip` + `$limit` from `QLPagination` input
 - Sort: `$sort` from `QLSortExpression` input
+- AND/OR: optional `AND`/`OR` arguments containing `QLFilterGroup` trees. Flat field filters and scope-injected filters are always ANDed at the top level (cannot be bypassed by user OR).
 
-`buildAggregationQuery()` extends this with `$group` for aggregation operations (SUM, COUNT, AVG, MIN, MAX).
+`buildAggregationQuery()` extends this with `$group` for aggregation operations (SUM, COUNT, AVG, MIN, MAX). Supports the same AND/OR filter pattern.
 
 ## Mutation Pipeline
 

package/README.md

@@ -265,6 +265,208 @@ query {
 - `NIN` - Not in array
 - `BTW` - Between two values
 
+### Logical Filters (AND / OR)
+
+By default, all field-level filters are combined with implicit AND logic. For complex conditions requiring OR logic or nested combinations, use the `AND` and `OR` query arguments.
+
+#### Simple OR
+
+Return books in either the Sci-Fi or Fantasy category:
+
+```graphql
+query {
+  books(
+    OR: [
+      { conditions: [{ field: "category", operator: EQ, value: "Sci-Fi" }] }
+      { conditions: [{ field: "category", operator: EQ, value: "Fantasy" }] }
+    ]
+  ) {
+    id
+    title
+    category
+  }
+}
+```
+
+#### Flat Filters Combined with OR
+
+Flat field filters are always ANDed at the top level, making them ideal for scope/security conditions that cannot be bypassed by user OR logic:
+
+```graphql
+query {
+  books(
+    rating: { operator: GTE, value: 7.0 }
+    OR: [
+      { conditions: [{ field: "category", operator: EQ, value: "Sci-Fi" }] }
+      { conditions: [{ field: "category", operator: EQ, value: "Fantasy" }] }
+    ]
+  ) {
+    id
+    title
+  }
+}
+```
+
+This translates to: `rating >= 7.0 AND (category = "Sci-Fi" OR category = "Fantasy")`.
+
+#### Nested AND inside OR
+
+```graphql
+query {
+  books(
+    OR: [
+      { AND: [
+        { conditions: [{ field: "rating", operator: GTE, value: 9.0 }] }
+        { conditions: [{ field: "category", operator: EQ, value: "Sci-Fi" }] }
+      ]}
+      { AND: [
+        { conditions: [{ field: "rating", operator: GTE, value: 8.0 }] }
+        { conditions: [{ field: "category", operator: EQ, value: "Fantasy" }] }
+      ]}
+    ]
+  ) {
+    id
+    title
+  }
+}
+```
+
+This translates to: `(rating >= 9.0 AND category = "Sci-Fi") OR (rating >= 8.0 AND category = "Fantasy")`.
+
+#### Filtering on Relationships within AND/OR
+
+Use the `path` parameter to filter on related entity fields:
+
+```graphql
+query {
+  books(
+    OR: [
+      { conditions: [{ field: "author", path: "name", operator: LIKE, value: "Adams" }] }
+      { conditions: [{ field: "author", path: "name", operator: LIKE, value: "Pratchett" }] }
+    ]
+  ) {
+    id
+    title
+    author { name }
+  }
+}
+```
+
+#### Mixing Flat Filters with AND/OR
+
+You can freely combine the existing flat filter syntax with AND/OR groups. Flat filters and AND groups are all ANDed together at the top level:
+
+```graphql
+query {
+  books(
+    rating: { operator: GTE, value: 7.0 }
+    author: { terms: [{ path: "country", operator: EQ, value: "UK" }] }
+    OR: [
+      { conditions: [{ field: "category", operator: EQ, value: "Sci-Fi" }] }
+      { conditions: [{ field: "category", operator: EQ, value: "Fantasy" }] }
+    ]
+  ) {
+    id
+    title
+    rating
+    category
+    author { name country }
+  }
+}
+```
+
+This translates to: `rating >= 7.0 AND author.country = "UK" AND (category = "Sci-Fi" OR category = "Fantasy")`. The flat field filters (`rating`, `author`) use the existing syntax while the OR group uses the new `QLFilterGroup` syntax.
+
+You can also combine flat filters with explicit AND groups for more complex logic:
+
+```graphql
+query {
+  books(
+    rating: { operator: GTE, value: 5.0 }
+    AND: [
+      {
+        OR: [
+          { conditions: [{ field: "category", operator: EQ, value: "Sci-Fi" }] }
+          { conditions: [{ field: "category", operator: EQ, value: "Fantasy" }] }
+        ]
+      }
+      {
+        OR: [
+          { conditions: [{ field: "author", path: "country", operator: EQ, value: "UK" }] }
+          { conditions: [{ field: "author", path: "country", operator: EQ, value: "US" }] }
+        ]
+      }
+    ]
+  ) {
+    id
+    title
+  }
+}
+```
+
+This translates to: `rating >= 5.0 AND (category = "Sci-Fi" OR category = "Fantasy") AND (author.country = "UK" OR author.country = "US")`.
+
+#### Collection Filtering with AND/OR
+
+AND/OR filters are also available on collection fields (one-to-many relationships). The auto-generated resolvers for collection fields support the same `AND` and `OR` arguments:
+
+```graphql
+query {
+  series {
+    seasons(
+      OR: [
+        { conditions: [{ field: "year", operator: EQ, value: 2020 }] }
+        { conditions: [{ field: "year", operator: EQ, value: 2021 }] }
+      ]
+    ) {
+      number
+      year
+    }
+  }
+}
+```
+
+You can mix flat collection filters with AND/OR:
+
+```graphql
+query {
+  series {
+    seasons(
+      number: { operator: GT, value: 1 }
+      OR: [
+        { conditions: [{ field: "year", operator: EQ, value: 2020 }] }
+        {
+          AND: [
+            { conditions: [{ field: "year", operator: GTE, value: 2022 }] }
+            { conditions: [
+                { field: "episodes", path: "name", operator: LIKE, value: "Final" }
+            ] }
+          ]
+        }
+      ]
+    ) {
+      number
+      year
+      episodes { name }
+    }
+  }
+}
+```
+
+This translates to: `number > 1 AND (year = 2020 OR (year >= 2022 AND episodes.name LIKE "Final"))`.
+
+#### Filter Types Reference
+
+| Type | Fields | Description |
+|------|--------|-------------|
+| `QLFilterGroup` | `AND: [QLFilterGroup]`, `OR: [QLFilterGroup]`, `conditions: [QLFilterCondition]` | Recursive logical group |
+| `QLFilterCondition` | `field: String!`, `operator: QLOperator`, `value: QLValue`, `path: String` | Individual filter condition |
+
+- `field` identifies the entity field by name (e.g., `"title"`, `"author"`)
+- `path` is required for object/relationship fields (e.g., `"name"`, `"country.name"`)
+- Multiple `conditions` in the same group are combined with AND
+- Maximum nesting depth: 5 levels
+
 ### Collection Field Filtering
 
 Simfinity.js now supports filtering collection fields (one-to-many relationships) using the same powerful query format. This allows you to filter related objects directly within your GraphQL queries.

package/git-report.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+
+import { execFileSync } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const CHANGE_TYPE_LABELS = {
+  A: 'Added',
+  M: 'Modified',
+  D: 'Deleted',
+  R: 'Renamed',
+  C: 'Copied',
+  T: 'TypeChanged',
+};
+
+const COMMIT_DELIMITER = '---GIT_REPORT_COMMIT---';
+const FIELD_DELIMITER = '---GIT_REPORT_FIELD---';
+
+function printHelp() {
+  const help = `
+Usage: node git-report.js --branch <branch> --author <author> --months <N> [--output <file.csv>]
+
+Generate a CSV report of git commits for a given author on a branch within a time period.
+
+Required arguments:
+  --branch <branch>   Git branch name to analyze
+  --author <author>   Git author name or email to filter by
+  --months <N>        Number of months to look back from today
+
+Optional arguments:
+  --output <file>     Output CSV file path (default: git-report.csv)
+  --help, -h          Show this help message and exit
+
+Output:
+  A CSV file with one row per affected file per commit, containing:
+    commit_hash, author, date, message, change_type, file_path
+
+Examples:
+  node git-report.js --branch master --author "John Doe" --months 3
+  node git-report.js --branch main --author john@example.com --months 6 --output report.csv
+`;
+  console.log(help.trim());
+}
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    process.exit(0);
+  }
+
+  const opts = {};
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case '--branch':
+        opts.branch = args[++i];
+        break;
+      case '--author':
+        opts.author = args[++i];
+        break;
+      case '--months':
+        opts.months = args[++i];
+        break;
+      case '--output':
+        opts.output = args[++i];
+        break;
+      default:
+        console.error(`Unknown argument: ${args[i]}`);
+        printHelp();
+        process.exit(1);
+    }
+  }
+
+  const missing = [];
+  if (!opts.branch) missing.push('--branch');
+  if (!opts.author) missing.push('--author');
+  if (!opts.months) missing.push('--months');
+
+  if (missing.length > 0) {
+    console.error(`Missing required arguments: ${missing.join(', ')}`);
+    printHelp();
+    process.exit(1);
+  }
+
+  const months = parseInt(opts.months, 10);
+  if (Number.isNaN(months) || months <= 0) {
+    console.error('--months must be a positive integer');
+    process.exit(1);
+  }
+  opts.months = months;
+  opts.output = opts.output || 'git-report.csv';
+
+  return opts;
+}
+
+function validateGitEnvironment() {
+  try {
+    execFileSync('git', ['--version'], { stdio: 'pipe' });
+  } catch {
+    console.error('Error: git is not installed or not found in PATH.');
+    process.exit(1);
+  }
+
+  try {
+    execFileSync('git', ['rev-parse', '--is-inside-work-tree'], { stdio: 'pipe' });
+  } catch {
+    console.error('Error: current directory is not inside a git repository.');
+    process.exit(1);
+  }
+}
+
+function computeSinceDate(months) {
+  const date = new Date();
+  date.setMonth(date.getMonth() - months);
+  return date.toISOString().slice(0, 10);
+}
+
+function escapeCsvField(value) {
+  const str = String(value).replace(/\r?\n/g, ' ');
+  if (str.includes(',') || str.includes('"') || str.includes('\n')) {
+    return `"${str.replace(/"/g, '""')}"`;
+  }
+  return str;
+}
+
+function getGitLog(branch, author, sinceDate) {
+  const format = [
+    `${COMMIT_DELIMITER}`,
+    `%h${FIELD_DELIMITER}%an${FIELD_DELIMITER}%ai${FIELD_DELIMITER}%s`,
+  ].join('');
+
+  const args = [
+    'log',
+    `--format=${format}`,
+    '--name-status',
+    `--author=${author}`,
+    `--since=${sinceDate}`,
+    branch,
+  ];
+
+  try {
+    return execFileSync('git', args, { encoding: 'utf-8', maxBuffer: 50 * 1024 * 1024 });
+  } catch (err) {
+    console.error(`Error running git log: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+function parseGitLog(rawOutput) {
+  const rows = [];
+  const commits = rawOutput.split(COMMIT_DELIMITER).filter((s) => s.trim());
+
+  for (const block of commits) {
+    const lines = block.trim().split('\n');
+    if (lines.length === 0) continue;
+
+    const headerLine = lines[0];
+    const parts = headerLine.split(FIELD_DELIMITER);
+    if (parts.length < 4) continue;
+
+    const [hash, author, dateRaw, message] = parts;
+    const date = dateRaw.slice(0, 10);
+
+    for (let i = 1; i < lines.length; i++) {
+      const line = lines[i].trim();
+      if (!line) continue;
+
+      const match = line.match(/^([AMDRTC])\d*\t(.+)$/);
+      if (!match) continue;
+
+      const statusCode = match[1];
+      const filePath = match[2].includes('\t') ? match[2].split('\t').pop() : match[2];
+      const changeType = CHANGE_TYPE_LABELS[statusCode] || statusCode;
+
+      rows.push({
+        commit_hash: hash,
+        author,
+        date,
+        message,
+        change_type: changeType,
+        file_path: filePath,
+      });
+    }
+  }
+
+  return rows;
+}
+
+function writeCsv(rows, outputPath) {
+  const columns = ['commit_hash', 'author', 'date', 'message', 'change_type', 'file_path'];
+  const header = columns.join(',');
+  const lines = rows.map((row) => columns.map((col) => escapeCsvField(row[col])).join(','));
+
+  const csv = [header, ...lines, ''].join('\n');
+  const absPath = resolve(outputPath);
+  writeFileSync(absPath, csv, 'utf-8');
+  return absPath;
+}
+
+function main() {
+  const opts = parseArgs(process.argv);
+  validateGitEnvironment();
+
+  const sinceDate = computeSinceDate(opts.months);
+  console.error(`Searching commits on branch "${opts.branch}" by "${opts.author}" since ${sinceDate}...`);
+
+  const rawLog = getGitLog(opts.branch, opts.author, sinceDate);
+  const rows = parseGitLog(rawLog);
+
+  const uniqueCommits = new Set(rows.map((r) => r.commit_hash)).size;
+
+  if (rows.length === 0) {
+    console.error('No commits found matching the criteria.');
+    process.exit(0);
+  }
+
+  const absPath = writeCsv(rows, opts.output);
+
+  console.error(`Done. ${uniqueCommits} commit(s), ${rows.length} file change(s).`);
+  console.error(`Report written to: ${absPath}`);
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-js",
-  "version": "2.4.4",
+  "version": "2.5.0",
   "description": "",
   "main": "src/index.js",
   "type": "module",