@cbs-consulting/cds-linter 1.0.0

package/.commitlintrc

@@ -0,0 +1,5 @@
+{
+    "extends": [
+        "@commitlint/config-conventional"
+    ]
+}

package/.czrc

@@ -0,0 +1,3 @@
+{
+    "path": "cz-conventional-changelog"
+}

package/.devcontainer/devcontainer.json

@@ -0,0 +1,7 @@
+{
+	"name": "cds-linter",
+	"image": "mcr.microsoft.com/devcontainers/base:trixie",
+	"features": {
+		"ghcr.io/devcontainers/features/node:1": {}
+	}
+}

package/.gitattributes

@@ -0,0 +1,3 @@
+* text=auto eol=lf
+*.{cmd,[cC][mM][dD]} text eol=crlf
+*.{bat,[bB][aA][tT]} text eol=crlf

package/.releaserc

@@ -0,0 +1,37 @@
+{
+    "branches": [
+        "+([0-9])?(.{+([0-9]),x}).x",
+        "main",
+        "next",
+        "next-major",
+        {
+            "name": "beta",
+            "prerelease": true
+        },
+        {
+            "name": "alpha",
+            "prerelease": true
+        }
+    ],
+    "plugins": [
+        "@semantic-release/commit-analyzer",
+        "@semantic-release/release-notes-generator",
+        [
+            "@semantic-release/changelog",
+            {
+                "changelogFile": "docs/CHANGELOG.md"
+            }
+        ],
+        "@semantic-release/npm",
+        [
+            "@semantic-release/git",
+            {
+                "message": "chore(release): ${nextRelease.version} - <%= new Date().toLocaleDateString('de-DE', {year: 'numeric', month: 'numeric', day: 'numeric', hour: 'numeric', minute: 'numeric', timeZone: 'Europe/Berlin' }) %>",
+                "assets": [
+                    "docs/CHANGELOG.md",
+                    "package.json"
+                ]
+            }
+        ]
+    ]
+}

package/README.md

@@ -0,0 +1,122 @@
+# CDS Linter
+
+A lightweight TypeScript-based linter for CDS files.
+
+## Installation
+
+```bash
+npm install @cbs-consulting/cds-linter
+```
+
+## Usage
+
+### Command Line
+
+```bash
+# Lint current directory
+cds-lint
+
+# Lint specific files or directories
+cds-lint examples/
+cds-lint src/models/views.cds
+
+# JSON output
+cds-lint examples/ --format json
+```
+
+### Programmatic API
+
+```typescript
+import CDSLinter from '@cbs-consulting/cds-linter';
+
+const linter = new CDSLinter();
+const results = await linter.lintDirectory('./db');
+
+console.log(`Found ${results.errorCount} errors`);
+```
+
+## The Rule
+
+### `group-by-matches-keys` (error)
+
+Validates that GROUP BY clauses in CDS views match the key structure:
+
+1. **All key columns must be in GROUP BY** - Every column marked as `key` in the SELECT must appear in the GROUP BY clause
+2. **Only key columns in GROUP BY** - No non-key columns should appear in the GROUP BY clause
+
+**Why?** This ensures that aggregated views have a proper, consistent key structure that matches the grouping logic. It prevents common mistakes where:
+- Keys are incomplete, leading to ambiguous aggregation results
+- Non-key fields are grouped, which should instead be aggregated
+
+### Examples
+
+✅ **Good:**
+```cds
+entity OrderSummary as
+  select from Orders as o {
+    key o.ID,
+    key o.OrderNo,
+    sum(o.price) as totalPrice
+  }
+  group by
+    o.ID,
+    o.OrderNo;  // All keys present, no non-keys
+```
+
+❌ **Bad:**
+```cds
+entity OrderSummary as
+  select from Orders as o {
+    key o.ID,
+    key o.OrderNo,
+    sum(o.price) as totalPrice
+  }
+  group by
+    o.ID;  // ERROR: Missing key o.OrderNo
+```
+
+❌ **Bad:**
+```cds
+entity OrderSummary as
+  select from Orders as o {
+    key o.ID,
+    o.quantity,
+    sum(o.price) as totalPrice
+  }
+  group by
+    o.ID,
+    o.quantity;  // ERROR: quantity is not a key
+```
+
+## Development
+
+### Building
+
+```bash
+npm run build      # Compile TypeScript
+npm run watch      # Watch mode
+```
+
+### Testing
+
+```bash
+npm test           # Run tests
+npm run test:watch # Watch mode
+```
+
+## Integration
+
+### npm scripts
+```json
+{
+  "scripts": {
+    "lint:cds": "cds-lint db/",
+    "ci": "npm run lint:cds && npm test"
+  }
+}
+```
+
+### CI/CD
+```yaml
+- run: npm run lint:cds
+```

package/azure-pipelines.yml

@@ -0,0 +1,39 @@
+trigger:
+  - main
+
+pool:
+  vmImage: "ubuntu-latest"
+
+parameters:
+  - name: node_version
+    type: string
+    default: "22.x"
+
+steps:
+  - task: UseNode@1
+    inputs:
+      version: ${{ parameters.node_version }}
+    displayName: "⚙️ Use node ${{ parameters.node_version }}"
+
+  - task: DownloadSecureFile@1
+    name: npmrc
+    inputs:
+      secureFile: ".npmrc"
+    displayName: "Download secure file"
+
+  - script: |
+      mv $(npmrc.secureFilePath) ./
+    displayName: "Move secure file"
+
+  - script: |
+      npm install
+    displayName: "Install dependencies..."
+
+  - script: |
+      AUTH=$(echo -n ":$SYSTEM_ACCESSTOKEN" | openssl base64 | tr -d '\n')
+      git config --global http."https://cbsCCCP@dev.azure.com".extraheader "AUTHORIZATION: basic $AUTH"
+      npx --no semantic-release
+    condition: and(succeeded(), ne(variables['Build.Reason'], 'PullRequest'))
+    displayName: "Run Release"
+    env:
+      SYSTEM_ACCESSTOKEN: $(System.AccessToken)

package/docs/CHANGELOG.md

@@ -0,0 +1,14 @@
+# 1.0.0 (2026-02-08)
+
+
+### Features
+
+* add azure pipeline config ([bfac30b](https://dev.azure.com/cbsCCCP/CBS_SWE/_git/cds-linter/commit/bfac30bd5bd824cfb1f1d3d0cf9b653b88c0977d))
+* add CDSLinter api ([e0e79a6](https://dev.azure.com/cbsCCCP/CBS_SWE/_git/cds-linter/commit/e0e79a684e84620edc2a35ab2ac0472dde75430a))
+* add cli parser ([136faec](https://dev.azure.com/cbsCCCP/CBS_SWE/_git/cds-linter/commit/136faec4d913c15320e9f41c8eda165c1c8d1001))
+* add devcontainer ([bdf04ea](https://dev.azure.com/cbsCCCP/CBS_SWE/_git/cds-linter/commit/bdf04ea572f83f0634ec617410cd3fa1ef178d34))
+* add group by rule ([149cbff](https://dev.azure.com/cbsCCCP/CBS_SWE/_git/cds-linter/commit/149cbffd6d936f4a9ae2f7ee67b00ddff7522148))
+* add reporter class ([23a1bfe](https://dev.azure.com/cbsCCCP/CBS_SWE/_git/cds-linter/commit/23a1bfe695a3cb6b6f92291d6366ac53fd627095))
+* add test cases ([e634c0d](https://dev.azure.com/cbsCCCP/CBS_SWE/_git/cds-linter/commit/e634c0d6cab1afaa22369aa922a32b3133831899))
+* cds parser ([6cf862e](https://dev.azure.com/cbsCCCP/CBS_SWE/_git/cds-linter/commit/6cf862e7de47e257aea2b94041a2b241509443c2))
+* commit tools ([8f105c3](https://dev.azure.com/cbsCCCP/CBS_SWE/_git/cds-linter/commit/8f105c3e0c03f91b4fe74c2f116d6e6f1ed7fac0))

package/examples/bad-example.cds

@@ -0,0 +1,69 @@
+namespace example;
+
+// Base entity for examples
+entity Orders {
+  key ID       : UUID;
+  key OrderNo  : String(10);
+  customerID   : UUID;
+  productID    : UUID;
+  quantity     : Integer;
+  price        : Decimal(10, 2);
+  orderDate    : Date;
+}
+
+/**
+ * BAD EXAMPLE 1: Missing key in GROUP BY
+ * ERROR: Key 'o.OrderNo' is selected but not in GROUP BY
+ */
+entity BadExample1 as
+  select from Orders as o {
+    key o.ID,
+    key o.OrderNo,
+    sum(o.price) as totalPrice
+  }
+  group by
+    o.ID;
+    // Missing: o.OrderNo
+
+/**
+ * BAD EXAMPLE 2: Non-key column in GROUP BY
+ * ERROR: quantity is not a key but is in GROUP BY
+ */
+entity BadExample2 as
+  select from Orders as o {
+    key o.ID,
+    o.quantity,
+    sum(o.price) as totalPrice
+  }
+  group by
+    o.ID,
+    o.quantity;  // BAD: quantity should not be in GROUP BY
+
+/**
+ * BAD EXAMPLE 3: Extra non-key field in GROUP BY
+ * ERROR: customerID is not a key but is in GROUP BY
+ */
+entity BadExample3 as
+  select from Orders as o {
+    key o.productID,
+    count(*) as orderCount
+  }
+  group by
+    o.productID,
+    o.customerID;  // BAD: customerID is not a key
+
+/**
+ * BAD EXAMPLE 4: Multiple violations
+ * ERROR: Missing key o.OrderNo in GROUP BY
+ * ERROR: Non-key o.customerID in GROUP BY
+ */
+entity BadExample4 as
+  select from Orders as o {
+    key o.ID,
+    key o.OrderNo,
+    o.customerID,
+    sum(o.price) as totalPrice
+  }
+  group by
+    o.ID,
+    o.customerID;  // BAD: Missing o.OrderNo, and customerID shouldn't be here

package/examples/good-example.cds

@@ -0,0 +1,55 @@
+namespace example;
+
+// Base entity for examples
+entity Orders {
+  key ID       : UUID;
+  keyOrderNo  : String(10);
+  customerID   : UUID;
+  productID    : UUID;
+  quantity     : Integer;
+  price        : Decimal(10, 2);
+  orderDate    : Date;
+}
+
+/**
+ * GOOD EXAMPLE: Keys match GROUP BY exactly
+ * All key columns (ID, OrderNo) are in GROUP BY
+ * No non-key columns are in GROUP BY
+ */
+entity OrderSummary as
+  select from Orders as o {
+    key o.ID,
+    key o.OrderNo,
+    min(o.quantity) as minQuantity,
+    sum(o.price) as totalPrice
+  }
+  group by
+    o.ID,
+    o.OrderNo;
+
+/**
+ * GOOD EXAMPLE: Single key matches GROUP BY
+ */
+entity CustomerOrders as
+  select from Orders as o {
+    key o.customerID,
+    count(*) as orderCount,
+    sum(o.price) as totalSpent
+  }
+  group by
+    o.customerID;
+
+/**
+ * GOOD EXAMPLE: Composite key with aggregations
+ */
+entity ProductDailySales as
+  select from Orders as o {
+    key o.productID,
+    key o.orderDate,
+    sum(o.quantity) as totalQuantity,
+    avg(o.price) as avgPrice,
+    max(o.price) as maxPrice
+  }
+  group by
+    o.productID,
+    o.orderDate;

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@cbs-consulting/cds-linter",
+  "version": "1.0.0",
+  "description": "Lightweight CDS file linter with GROUP BY validation.",
+  "main": "dist/index.js",
+  "bin": {
+    "cds-lint": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "start": "npm run build && node dist/cli.js",
+    "dev": "ts-node src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist",
+    "commit": "git add . && npx cz"
+  },
+  "dependencies": {
+    "@sap/cds": "^7.5.0",
+    "chalk": "^4.1.2",
+    "commander": "^11.1.0",
+    "glob": "^10.3.10"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "20.4.1",
+    "@commitlint/config-conventional": "20.4.1",
+    "@semantic-release/changelog": "6.0.3",
+    "@semantic-release/git": "10.0.1",
+    "commitizen": "4.3.1",
+    "cz-conventional-changelog": "3.3.0",
+    "semantic-release": "25.0.3",
+    "@types/node": "^20.10.5",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3",
+    "vitest": "^2.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/__tests__/index.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import CDSLinter from '../index';
+import * as path from 'path';
+
+describe('CDSLinter', () => {
+  let linter: CDSLinter;
+
+  beforeEach(() => {
+    linter = new CDSLinter();
+  });
+
+  describe('Basic functionality', () => {
+    it('should create a linter instance', () => {
+      expect(linter).toBeInstanceOf(CDSLinter);
+    });
+
+    it('should lint a CDS file and return results', async () => {
+      const testFile = path.join(__dirname, '../../examples/good-example.cds');
+      const results = await linter.lintFiles([testFile]);
+
+      expect(results).toHaveProperty('files');
+      expect(results).toHaveProperty('errorCount');
+      expect(results).toHaveProperty('warningCount');
+      expect(Array.isArray(results.files)).toBe(true);
+    });
+
+    it('should pass validation for correct GROUP BY usage', async () => {
+      const testFile = path.join(__dirname, '../../examples/good-example.cds');
+      const results = await linter.lintFiles([testFile]);
+
+      // Good examples should have no errors
+      expect(results.errorCount).toBe(0);
+    });
+
+    it('should detect GROUP BY violations in bad examples', async () => {
+      const testFile = path.join(__dirname, '../../examples/bad-example.cds');
+      const results = await linter.lintFiles([testFile]);
+
+      // Should have errors for GROUP BY not matching keys
+      expect(results.errorCount).toBeGreaterThan(0);
+      
+      // Check that the rule ID is correct
+      const hasGroupByError = results.files.some(file =>
+        file.messages.some(msg => msg.ruleId === 'group-by-matches-keys')
+      );
+      expect(hasGroupByError).toBe(true);
+    });
+
+    it('should return null for non-CDS files', async () => {
+      const results = await linter.lintFiles(['test.js']);
+      expect(results.files.length).toBe(0);
+    });
+  });
+
+  describe('Directory linting', () => {
+    it('should lint all CDS files in a directory', async () => {
+      const examplesDir = path.join(__dirname, '../../examples');
+      const results = await linter.lintDirectory(examplesDir);
+
+      // Should find both example files
+      expect(results.files.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('Configuration', () => {
+    it('should create a linter instance with default configuration', () => {
+      const customLinter = new CDSLinter();
+      expect(customLinter).toBeInstanceOf(CDSLinter);
+    });
+  });
+});

package/src/cds-linter.ts

@@ -0,0 +1,110 @@
+import cds from '@sap/cds';
+import * as fs from 'fs';
+import { CSN, LintResult, Rule, Definition } from './types/cds';
+
+/**
+ * CDS file parser and rule executor
+ */
+export default class CDSParser {
+  constructor(private rules: Rule[]) {}
+
+  /**
+   * Lint a CDS file
+   * @param filePath - Path to CDS file
+   * @returns Lint results for the file
+   */
+  async lintFile(filePath: string): Promise<LintResult | null> {
+    if (!filePath.endsWith('.cds')) {
+      return null;
+    }
+
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`File not found: ${filePath}`);
+    }
+
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const results: LintResult = {
+      filePath,
+      messages: [],
+      errorCount: 0,
+      warningCount: 0,
+      fixableErrorCount: 0,
+      fixableWarningCount: 0
+    };
+
+    try {
+      // Parse CDS file using @sap/cds compiler
+      const csn = await cds.compile.to.csn(content, {
+        flavor: 'parsed',
+        docs: true
+      }) as CSN;
+
+      // Apply rules to parsed CSN
+      for (const rule of this.rules) {
+        if (rule.enabled !== false) {
+          const violations = await rule.check(csn, content, filePath);
+          if (violations && violations.length > 0) {
+            results.messages.push(...violations);
+            
+            for (const violation of violations) {
+              if (violation.severity === 'error') {
+                results.errorCount++;
+                if (violation.fixable) results.fixableErrorCount++;
+              } else if (violation.severity === 'warning') {
+                results.warningCount++;
+                if (violation.fixable) results.fixableWarningCount++;
+              }
+            }
+          }
+        }
+      }
+
+    } catch (error: any) {
+      // Report parsing errors
+      results.messages.push({
+        ruleId: 'parse-error',
+        severity: 'error',
+        message: error.message,
+        line: error.line || 1,
+        column: error.column || 1
+      });
+      results.errorCount++;
+    }
+
+    return results;
+  }
+
+  /**
+   * Extract entities from CSN
+   * @param csn - Compiled CSN
+   * @returns List of entities
+   */
+  getEntities(csn: CSN): Array<{ name: string; definition: Definition }> {
+    const entities: Array<{ name: string; definition: Definition }> = [];
+    if (csn.definitions) {
+      for (const [name, definition] of Object.entries(csn.definitions)) {
+        if (definition.kind === 'entity' || definition.kind === 'type') {
+          entities.push({ name, definition });
+        }
+      }
+    }
+    return entities;
+  }
+
+  /**
+   * Extract services from CSN
+   * @param csn - Compiled CSN
+   * @returns List of services
+   */
+  getServices(csn: CSN): Array<{ name: string; definition: Definition }> {
+    const services: Array<{ name: string; definition: Definition }> = [];
+    if (csn.definitions) {
+      for (const [name, definition] of Object.entries(csn.definitions)) {
+        if (definition.kind === 'service') {
+          services.push({ name, definition });
+        }
+      }
+    }
+    return services;
+  }
+}

package/src/cli.ts

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import CDSLinter from './index';
+import Reporter from './utils/reporter';
+import * as path from 'path';
+import * as fs from 'fs';
+
+const program = new Command();
+
+program
+  .name('cds-lint')
+  .description('Linter for CDS files')
+  .version('0.1.0')
+  .argument('[paths...]', 'Files or directories to lint', ['.'])
+  .option('--format <type>', 'Output format (stylish or json)', 'stylish')
+  .action(async (paths: string[], options: any) => {
+    try {
+      // Initialize linter
+      const linter = new CDSLinter();
+
+      // Determine what to lint
+      const targets: string[] = [];
+      for (const targetPath of paths) {
+        const resolved = path.resolve(targetPath);
+        if (fs.existsSync(resolved)) {
+          const stat = fs.statSync(resolved);
+          if (stat.isDirectory()) {
+            targets.push(resolved);
+          } else if (stat.isFile()) {
+            targets.push(resolved);
+          }
+        } else {
+          console.error(`Path not found: ${targetPath}`);
+        }
+      }
+
+      // Lint files
+      let results;
+      if (targets.length === 1 && fs.statSync(targets[0]).isDirectory()) {
+        results = await linter.lintDirectory(targets[0]);
+      } else {
+        results = await linter.lintFiles(targets);
+      }
+
+      // Report results
+      const reporter = new Reporter(options.format);
+      reporter.report(results);
+
+      // Exit with appropriate code
+      process.exit(results.errorCount > 0 ? 1 : 0);
+
+    } catch (error: any) {
+      console.error('Error:', error.message);
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/src/index.ts

@@ -0,0 +1,59 @@
+import CDSParser from './cds-linter';
+import * as rules from './rules';
+import { LintResults } from './types/cds';
+import { glob } from 'glob';
+import * as path from 'path';
+
+/**
+ * CDS Linter - Main entry point
+ */
+export default class CDSLinter {
+  private parser: CDSParser;
+
+  constructor() {
+    this.parser = new CDSParser(rules.getDefaultRules());
+  }
+
+  /**
+   * Lint files in given paths
+   * @param paths - File paths or glob patterns
+   * @returns Lint results
+   */
+  async lintFiles(paths: string[]): Promise<LintResults> {
+    const results: LintResults = {
+      files: [],
+      errorCount: 0,
+      warningCount: 0,
+      fixableErrorCount: 0,
+      fixableWarningCount: 0
+    };
+
+    // Lint CDS files
+    for (const filePath of paths) {
+      const fileResults = await this.parser.lintFile(filePath);
+      if (fileResults) {
+        results.files.push(fileResults);
+        results.errorCount += fileResults.errorCount;
+        results.warningCount += fileResults.warningCount;
+        results.fixableErrorCount += fileResults.fixableErrorCount;
+        results.fixableWarningCount += fileResults.fixableWarningCount;
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Lint a directory
+   * @param directory - Directory path
+   * @returns Lint results
+   */
+  async lintDirectory(directory: string): Promise<LintResults> {
+    const pattern = path.join(directory, '**/*.cds');
+    const files = await glob(pattern);
+    
+    return this.lintFiles(files);
+  }
+}
+
+module.exports = CDSLinter;

package/src/rules/cds-rules.ts

@@ -0,0 +1,114 @@
+import { Rule, CSN, LintMessage } from '../types/cds';
+
+/**
+ * Rule: Group By must match key properties exactly
+ * Ensures that in CDS views with GROUP BY:
+ * 1. All key properties are present in GROUP BY
+ * 2. Only key properties are present in GROUP BY (no non-key fields)
+ */
+export const groupByMatchesKeys: Rule = {
+  name: 'group-by-matches-keys',
+  enabled: true,
+  severity: 'error',
+  
+  async check(csn: CSN, content: string, filePath: string): Promise<LintMessage[]> {
+    const messages: LintMessage[] = [];
+
+    if (!csn.definitions) return messages;
+
+    for (const [entityName, definition] of Object.entries(csn.definitions)) {
+      // Check if this is a view/projection with a query
+      if (definition.kind === 'entity' && definition.query) {
+        const query = definition.query;
+        
+        // Check if there's a GROUP BY clause
+        if (query.SELECT?.groupBy) {
+          const groupBy = query.SELECT.groupBy;
+          const columns = query.SELECT.columns || [];
+          
+          // Extract key columns from the SELECT
+          const keyColumns = new Set<string>();
+          const nonKeyColumns = new Set<string>();
+          
+          for (const col of columns) {
+            if (col.ref) {
+              const columnName = Array.isArray(col.ref) ? col.ref.join('.') : col.ref;
+              const columnAlias = col.as || columnName;
+              
+              if (col.key === true) {
+                keyColumns.add(columnName);
+              } else if (col.key !== true && !isAggregateFunction(col)) {
+                nonKeyColumns.add(columnName);
+              }
+            }
+          }
+          
+          // Extract GROUP BY references
+          const groupByRefs = new Set<string>();
+          for (const groupByItem of groupBy) {
+            if (groupByItem.ref) {
+              const refName = Array.isArray(groupByItem.ref) ? groupByItem.ref.join('.') : groupByItem.ref;
+              groupByRefs.add(refName);
+            }
+          }
+          
+          // Check 1: All keys must be in GROUP BY
+          for (const keyCol of keyColumns) {
+            if (!groupByRefs.has(keyCol)) {
+              messages.push({
+                ruleId: 'group-by-matches-keys',
+                severity: 'error',
+                message: `Key column '${keyCol}' in entity '${entityName}' must be present in GROUP BY clause`,
+                line: 1,
+                column: 1,
+                fixable: false
+              });
+            }
+          }
+          
+          // Check 2: GROUP BY should only contain key columns (no non-key columns)
+          for (const groupByRef of groupByRefs) {
+            if (!keyColumns.has(groupByRef) && nonKeyColumns.has(groupByRef)) {
+              messages.push({
+                ruleId: 'group-by-matches-keys',
+                severity: 'error',
+                message: `Non-key column '${groupByRef}' in entity '${entityName}' should not be in GROUP BY clause. Only key columns are allowed.`,
+                line: 1,
+                column: 1,
+                fixable: false
+              });
+            }
+          }
+          
+          // Check 3: GROUP BY should not have columns that aren't selected as keys
+          for (const groupByRef of groupByRefs) {
+            if (!keyColumns.has(groupByRef) && !nonKeyColumns.has(groupByRef)) {
+              // This might be OK if it's just not selected, but warn anyway
+              messages.push({
+                ruleId: 'group-by-matches-keys',
+                severity: 'warning',
+                message: `Column '${groupByRef}' in GROUP BY of entity '${entityName}' is not defined as a key in the SELECT`,
+                line: 1,
+                column: 1,
+                fixable: false
+              });
+            }
+          }
+        }
+      }
+    }
+
+    return messages;
+  }
+};
+
+/**
+ * Helper to check if a column uses an aggregate function
+ */
+function isAggregateFunction(col: any): boolean {
+  if (col.func) {
+    const funcName = col.func.toLowerCase();
+    return ['min', 'max', 'sum', 'avg', 'count'].includes(funcName);
+  }
+  return false;
+}

package/src/rules/index.ts

@@ -0,0 +1,25 @@
+import { Rule } from '../types/cds';
+import * as cdsRules from './cds-rules';
+
+/**
+ * Get default set of enabled rules
+ */
+export function getDefaultRules(): Rule[] {
+  return [
+    cdsRules.groupByMatchesKeys
+  ];
+}
+
+/**
+ * Get all available rules
+ */
+export function getAllRules(): Rule[] {
+  return getDefaultRules();
+}
+
+/**
+ * Get a rule by name
+ */
+export function getRule(name: string): Rule | undefined {
+  return getAllRules().find(rule => rule.name === name);
+}

package/src/types/cds.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Type definitions for @sap/cds CSN structures
+ */
+
+export interface CSN {
+  definitions?: Record<string, Definition>;
+  namespace?: string;
+  requires?: Record<string, any>;
+  extensions?: any[];
+  $version?: string;
+}
+
+export interface Definition {
+  kind?: 'entity' | 'type' | 'service' | 'context' | 'aspect' | 'annotation' | 'action' | 'function' | 'event';
+  elements?: Record<string, Element>;
+  includes?: string[];
+  actions?: Record<string, Action>;
+  operations?: Record<string, Operation>;
+  '@': Record<string, any>; // Annotations
+  [key: string]: any;
+}
+
+export interface Element {
+  type?: string;
+  target?: string;
+  key?: boolean;
+  notNull?: boolean;
+  default?: any;
+  virtual?: boolean;
+  localized?: boolean;
+  items?: Element;
+  '@': Record<string, any>;
+  [key: string]: any;
+}
+
+export interface Action {
+  kind: 'action' | 'function';
+  params?: Record<string, Element>;
+  returns?: Element;
+  '@': Record<string, any>;
+}
+
+export interface Operation extends Action {}
+
+export interface LintMessage {
+  ruleId: string;
+  severity: 'error' | 'warning' | 'info';
+  message: string;
+  line: number;
+  column: number;
+  endLine?: number;
+  endColumn?: number;
+  fixable?: boolean;
+  fix?: () => string;
+}
+
+export interface LintResult {
+  filePath: string;
+  messages: LintMessage[];
+  errorCount: number;
+  warningCount: number;
+  fixableErrorCount: number;
+  fixableWarningCount: number;
+}
+
+export interface LintResults {
+  files: LintResult[];
+  errorCount: number;
+  warningCount: number;
+  fixableErrorCount: number;
+  fixableWarningCount: number;
+}
+
+export interface Rule {
+  name: string;
+  enabled: boolean;
+  severity: 'error' | 'warning' | 'info';
+  check: (csn: CSN, content: string, filePath: string) => Promise<LintMessage[]>;
+}

package/src/utils/reporter.ts

@@ -0,0 +1,91 @@
+import chalk from 'chalk';
+import { LintResults, LintResult, LintMessage } from '../types/cds';
+
+/**
+ * Reporter for displaying lint results
+ */
+export default class Reporter {
+  constructor(private format: string = 'stylish') {}
+
+  /**
+   * Report lint results
+   */
+  report(results: LintResults): void {
+    if (this.format === 'json') {
+      this.reportJson(results);
+    } else {
+      this.reportStylish(results);
+    }
+  }
+
+  /**
+   * Stylish format (default, colorful)
+   */
+  private reportStylish(results: LintResults): void {
+    if (results.files.length === 0) {
+      console.log(chalk.green('✓ No files to lint'));
+      return;
+    }
+
+    let hasProblems = false;
+
+    for (const file of results.files) {
+      if (file.messages.length > 0) {
+        hasProblems = true;
+        console.log('\n' + chalk.underline(file.filePath));
+        
+        for (const message of file.messages) {
+          const severityColor = message.severity === 'error' ? chalk.red : chalk.yellow;
+          const severityIcon = message.severity === 'error' ? '✖' : '⚠';
+          
+          console.log(
+            `  ${chalk.dim(`${message.line}:${message.column}`)}  ` +
+            `${severityColor(severityIcon)}  ${message.message}  ` +
+            `${chalk.dim(message.ruleId)}`
+          );
+        }
+      }
+    }
+
+    if (hasProblems) {
+      console.log('\n' + this.getSummary(results));
+    } else {
+      console.log(chalk.green('\n✓ No problems found'));
+    }
+  }
+
+  /**
+   * JSON format
+   */
+  private reportJson(results: LintResults): void {
+    console.log(JSON.stringify(results, null, 2));
+  }
+
+  /**
+   * Get summary text
+   */
+  private getSummary(results: LintResults): string {
+    const parts: string[] = [];
+    
+    if (results.errorCount > 0) {
+      parts.push(
+        chalk.red.bold(`✖ ${results.errorCount} ${this.pluralize('error', results.errorCount)}`)
+      );
+    }
+    
+    if (results.warningCount > 0) {
+      parts.push(
+        chalk.yellow.bold(`⚠ ${results.warningCount} ${this.pluralize('warning', results.warningCount)}`)
+      );
+    }
+    
+    return parts.join('  ');
+  }
+
+  /**
+   * Pluralize a word
+   */
+  private pluralize(word: string, count: number): string {
+    return count === 1 ? word : word + 's';
+  }
+}

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "moduleResolution": "node",
+    "types": ["node"],
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "vitest.config.ts"]
+}

package/vitest.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.{test,spec}.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: [
+        'node_modules/',
+        'src/**/*.d.ts',
+        'src/**/__tests__/**',
+        'dist/'
+      ]
+    }
+  }
+});