hana-linter 0.1.1

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,29 @@
+# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
+# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
+
+name: Publish NPM Package
+
+on:
+  push:
+    branches:
+      - main
+  release:
+    types: [created]
+
+permissions:
+  id-token: write # required for OIDC
+  contents: read
+  
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+      - run: npm run build --if-present
+      - run: npm test
+      - run: npm publish

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "tabWidth": 4,
+  "useTabs": false,
+  "singleQuote": true,
+  "trailingComma": "none",
+  "printWidth": 150
+}

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+---
+
+### 0.1.1
+
+- Added `hana-linter init` command to generate a default `.hana-linter.json` in the current project root
+- Added `hana-linter init --force` option to overwrite an existing config file
+
+### Initial Release
+
+- Initial version with core linter functionality

package/README.md

@@ -0,0 +1,286 @@
+# hana-linter
+
+[![npm version](https://img.shields.io/npm/v/hana-linter)](https://www.npmjs.com/package/hana-linter)
+[![CI](https://github.com/qualiture/hana-linter/actions/workflows/npm-publish.yml/badge.svg?branch=main)](https://github.com/qualiture/hana-linter/actions/workflows/npm-publish.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/qualiture/hana-linter/blob/main/LICENSE)
+[![Node >=14](https://img.shields.io/badge/node-%3E%3D14-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+
+Regex-first naming lint for SAP HANA artifacts in CAP projects.
+
+[NPM package](https://www.npmjs.com/package/hana-linter) • [Report issue](https://github.com/qualiture/hana-linter/issues) • [Releases](https://github.com/qualiture/hana-linter/releases)
+
+Lint SAP HANA artifact names in CAP projects using configurable regex-based naming rules.
+
+## Why
+
+Teams often rely on naming conventions for HANA artifacts such as tables and views. When these conventions are enforced manually, drift is common and code reviews become noisy.
+
+hana-linter helps you:
+
+- enforce naming standards consistently
+- catch violations early in local development and CI
+- apply different rules per file extension
+- keep naming policy in version control via a single config file
+
+## How It Works
+
+hana-linter reads a `.hana-linter.json` file and validates artifact file names against rules grouped by extension.
+
+It supports two lint modes:
+
+- Full scan mode: no file arguments, recursively scans `rootDir`
+- File-list mode: pass file paths, only those files are validated
+
+Rule groups per extension:
+
+- `groups.all`: every rule must match (AND)
+- `groups.any`: at least one rule must match (OR)
+
+You can define `extension: "*"` as a shared rule set. Its rules are applied to every file extension and are merged with any extension-specific rule set.
+
+## Install
+
+### Local (recommended for projects)
+
+```bash
+npm install --save-dev hana-linter
+```
+
+Run with:
+
+```bash
+npx hana-linter
+```
+
+### Global
+
+```bash
+npm install -g hana-linter
+```
+
+## Quick Start
+
+1. Generate a default config in your project root:
+
+```bash
+hana-linter init
+```
+
+2. Run the linter:
+
+```bash
+hana-linter
+```
+
+3. If needed, regenerate and overwrite config:
+
+```bash
+hana-linter init --force
+```
+
+## Commands
+
+### `hana-linter`
+
+Run lint using `.hana-linter.json` from the current working directory.
+
+```bash
+hana-linter
+```
+
+Lint specific files only:
+
+```bash
+hana-linter db/src/T_CUSTOMER.hdbtable db/src/V_ACTIVE_USERS.hdbview
+```
+
+Use a custom config path:
+
+```bash
+hana-linter --config ./config/.hana-linter.json
+```
+
+### `hana-linter init`
+
+Create `.hana-linter.json` in the current working directory from the bundled default template.
+
+```bash
+hana-linter init
+```
+
+Overwrite existing config:
+
+```bash
+hana-linter init --force
+```
+
+## Configuration
+
+Create a `.hana-linter.json` file in your project root.
+
+### Configuration Fields
+
+- `rootDir` (string): directory to scan in full scan mode
+- `ignoredDirectories` (string[]): folder names ignored during recursive traversal
+- `extensionRuleSets` (array): rule definitions grouped by file extension
+- `contentRuleSets` (optional array): naming rules for identifiers extracted from file contents (for example table fields and procedure/function parameters)
+
+Each `extensionRuleSets` item contains:
+
+- `extension` (string): target extension, for example `.hdbtable`; use `*` to target all extensions
+- `folderName` (optional string): enforce that matching files are located in a folder with this name (at any depth under `rootDir`)
+- `groups.all` (optional array): all rules must match
+- `groups.any` (optional array): at least one rule must match
+
+Each rule contains:
+
+- `description` (string): readable rule label for output
+- `pattern` (string): regex source (without `/` delimiters)
+- `flags` (optional string): regex flags, for example `i`, `u`, `iu`
+
+At least one of `groups.all` or `groups.any` must be present for each extension.
+
+When `folderName` is omitted, no folder-location enforcement is applied.
+
+Each `contentRuleSets` item contains:
+
+- `extension` (string): target extension, for example `.hdbtable`; use `*` to target all extensions
+- `target` (string): extracted identifier type to validate; one of `field`, `inputParameter`, `outputParameter`
+- `groups.all` (optional array): all rules must match
+- `groups.any` (optional array): at least one rule must match
+
+Supported extractors in this version:
+
+- `field`: `.hdbtable`
+- `inputParameter`: `.hdbprocedure`, `.hdbfunction`
+- `outputParameter`: `.hdbprocedure`, `.hdbfunction`
+
+### Default Config Example
+
+```json
+{
+    "rootDir": "db",
+    "ignoredDirectories": ["node_modules", ".git", "gen"],
+    "extensionRuleSets": [
+        {
+            "extension": "*",
+            "groups": {
+                "all": [
+                    {
+                        "description": "Upper snake case only",
+                        "pattern": "^[A-Z0-9]+(?:_[A-Z0-9]+)*$"
+                    },
+                    {
+                        "description": "Max length 30",
+                        "pattern": "^.{1,30}$",
+                        "flags": "u"
+                    }
+                ]
+            }
+        },
+        {
+            "extension": ".hdbtable",
+            "folderName": "tables",
+            "groups": {
+                "any": [
+                    {
+                        "description": "Prefix T_",
+                        "pattern": "^T_.+"
+                    },
+                    {
+                        "description": "Prefix TX_",
+                        "pattern": "^TX_.+"
+                    }
+                ]
+            }
+        },
+        {
+            "extension": ".hdbview",
+            "groups": {
+                "all": [
+                    {
+                        "description": "Starts with V_",
+                        "pattern": "^V_.+"
+                    }
+                ]
+            }
+        }
+    ],
+    "contentRuleSets": [
+        {
+            "extension": ".hdbtable",
+            "target": "field",
+            "groups": {
+                "all": [
+                    {
+                        "description": "Field names in uppercase snake case",
+                        "pattern": "^[A-Z0-9]+(?:_[A-Z0-9]+)*$"
+                    }
+                ]
+            }
+        },
+        {
+            "extension": ".hdbprocedure",
+            "target": "inputParameter",
+            "groups": {
+                "all": [
+                    {
+                        "description": "Input parameters prefixed with IP_",
+                        "pattern": "^IP_[A-Z0-9_]+$"
+                    }
+                ]
+            }
+        },
+        {
+            "extension": ".hdbprocedure",
+            "target": "outputParameter",
+            "groups": {
+                "all": [
+                    {
+                        "description": "Output parameters prefixed with OP_",
+                        "pattern": "^OP_[A-Z0-9_]+$"
+                    }
+                ]
+            }
+        }
+    ]
+}
+```
+
+## Exit Codes
+
+- `0`: lint passed or `init` completed successfully
+- `1`: lint violations found or command failed
+
+This makes the CLI suitable for CI pipelines.
+
+## CI Example
+
+```yaml
+name: lint-hana-names
+on: [push, pull_request]
+
+jobs:
+	hana-lint:
+		runs-on: ubuntu-latest
+		steps:
+			- uses: actions/checkout@v4
+			- uses: actions/setup-node@v4
+				with:
+					node-version: 20
+			- run: npm ci
+			- run: npx hana-linter
+```
+
+## Requirements
+
+- Node.js >= 14
+- npm >= 7
+
+## Contributing
+
+Contributions are welcome. Please open an issue or submit a pull request.
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,104 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCliInput = parseCliInput;
+exports.runInit = runInit;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const DEFAULT_CONFIG_PATH = '.hana-linter.json';
+/**
+ * Parse command-line arguments.
+ *
+ * Supported:
+ * - --config <path>
+ * - remaining arguments are treated as file paths
+ *
+ * @returns Parsed CLI input.
+ */
+function parseCliInput() {
+    const args = process.argv.slice(2);
+    if (args[0] === 'init') {
+        const initArgs = args.slice(1);
+        let force = false;
+        for (const value of initArgs) {
+            if (value === '--force') {
+                force = true;
+                continue;
+            }
+            throw new Error(`Unknown argument for init: "${value}". Supported: --force`);
+        }
+        return {
+            command: 'init',
+            files: [],
+            configPath: DEFAULT_CONFIG_PATH,
+            force
+        };
+    }
+    const files = [];
+    let configPath = DEFAULT_CONFIG_PATH;
+    for (let index = 0; index < args.length; index += 1) {
+        const value = args[index];
+        if (value === '--config') {
+            const nextValue = args[index + 1];
+            if (!nextValue || nextValue.startsWith('--')) {
+                throw new Error('Missing value for --config');
+            }
+            configPath = nextValue;
+            index += 1;
+            continue;
+        }
+        files.push(value);
+    }
+    return {
+        command: 'lint',
+        files: files.filter((value) => value.trim().length > 0),
+        configPath,
+        force: false
+    };
+}
+/**
+ * Create .hana-linter.json in current working directory from bundled template.
+ *
+ * @param force - Overwrite existing file when true.
+ */
+async function runInit(force) {
+    const templatePath = await resolveTemplateConfigPath();
+    const targetPath = node_path_1.default.resolve(process.cwd(), DEFAULT_CONFIG_PATH);
+    try {
+        await node_fs_1.promises.copyFile(templatePath, targetPath, force ? 0 : node_fs_1.constants.COPYFILE_EXCL);
+        console.info(`✅ Created ${DEFAULT_CONFIG_PATH} at ${targetPath}`);
+    }
+    catch (error) {
+        if (!force && typeof error === 'object' && error !== null && 'code' in error && error.code === 'EEXIST') {
+            throw new Error(`${DEFAULT_CONFIG_PATH} already exists at ${targetPath}. Use "hana-linter init --force" to overwrite.`);
+        }
+        throw error;
+    }
+}
+/**
+ * Resolve the packaged default config template path.
+ *
+ * Supports both:
+ * - built artifact layout (dist/assets)
+ * - source layout (src/assets) during local development
+ *
+ * @returns Existing template path.
+ */
+async function resolveTemplateConfigPath() {
+    const candidatePaths = [
+        node_path_1.default.resolve(__dirname, 'assets', DEFAULT_CONFIG_PATH),
+        node_path_1.default.resolve(__dirname, '..', 'src', 'assets', DEFAULT_CONFIG_PATH)
+    ];
+    for (const candidatePath of candidatePaths) {
+        try {
+            await node_fs_1.promises.access(candidatePath);
+            return candidatePath;
+        }
+        catch {
+            // Try next candidate.
+        }
+    }
+    throw new Error('Could not locate bundled default configuration template. Expected one of: ' + candidatePaths.join(', '));
+}

package/dist/config.js

@@ -0,0 +1,227 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readJsonConfig = readJsonConfig;
+exports.toLintConfig = toLintConfig;
+const node_fs_1 = require("node:fs");
+/**
+ * Read and parse JSON config file.
+ *
+ * @param configPath - Path to JSON configuration.
+ * @returns Parsed JSON config object.
+ */
+async function readJsonConfig(configPath) {
+    const rawContent = await node_fs_1.promises.readFile(configPath, { encoding: 'utf-8' });
+    const parsed = JSON.parse(rawContent);
+    if (!isJsonLintConfig(parsed)) {
+        throw new Error(`Invalid configuration schema in "${configPath}". Please verify required fields.`);
+    }
+    return parsed;
+}
+/**
+ * Convert JSON config into runtime compiled config.
+ *
+ * @param jsonConfig - Parsed JSON config.
+ * @returns Runtime lint config with compiled regex.
+ */
+function toLintConfig(jsonConfig) {
+    const extensionFolderNames = new Map();
+    const extensionRuleSets = jsonConfig.extensionRuleSets.map((jsonRuleSet) => {
+        const folderName = jsonRuleSet.folderName?.trim();
+        if (folderName !== undefined && folderName.length === 0) {
+            throw new Error(`Invalid folderName for extension "${jsonRuleSet.extension}": value must not be empty.`);
+        }
+        if (folderName !== undefined && (folderName.includes('/') || folderName.includes('\\'))) {
+            throw new Error(`Invalid folderName for extension "${jsonRuleSet.extension}": use only a folder name, not a path.`);
+        }
+        if (folderName !== undefined) {
+            const existingFolderName = extensionFolderNames.get(jsonRuleSet.extension);
+            if (existingFolderName && existingFolderName !== folderName) {
+                throw new Error(`Conflicting folderName values configured for extension "${jsonRuleSet.extension}": "${existingFolderName}" and "${folderName}".`);
+            }
+            extensionFolderNames.set(jsonRuleSet.extension, folderName);
+        }
+        const compiledGroups = compileRuleGroup(jsonRuleSet.groups, `extension "${jsonRuleSet.extension}"`);
+        const allRules = compiledGroups.all ?? [];
+        const anyRules = compiledGroups.any ?? [];
+        const hasAllRules = allRules.length > 0;
+        const hasAnyRules = anyRules.length > 0;
+        if (!hasAllRules && !hasAnyRules) {
+            throw new Error(`Invalid rule configuration for extension "${jsonRuleSet.extension}": at least one rule is required in "groups.all" or "groups.any".`);
+        }
+        return {
+            extension: jsonRuleSet.extension,
+            folderName,
+            groups: compiledGroups
+        };
+    });
+    const contentRuleSets = (jsonConfig.contentRuleSets ?? []).map((jsonRuleSet) => {
+        const compiledGroups = compileRuleGroup(jsonRuleSet.groups, `content target "${jsonRuleSet.target}" extension "${jsonRuleSet.extension}"`);
+        const hasAllRules = (compiledGroups.all ?? []).length > 0;
+        const hasAnyRules = (compiledGroups.any ?? []).length > 0;
+        if (!hasAllRules && !hasAnyRules) {
+            throw new Error(`Invalid content rule configuration for target "${jsonRuleSet.target}" extension "${jsonRuleSet.extension}": at least one rule is required in "groups.all" or "groups.any".`);
+        }
+        return {
+            extension: jsonRuleSet.extension,
+            target: jsonRuleSet.target,
+            groups: compiledGroups
+        };
+    });
+    return {
+        rootDir: jsonConfig.rootDir,
+        ignoredDirectories: jsonConfig.ignoredDirectories,
+        extensionRuleSets,
+        contentRuleSets
+    };
+}
+/**
+ * Basic runtime schema guard for JSON config.
+ *
+ * @param value - Unknown parsed JSON value.
+ * @returns True when value matches expected shape.
+ */
+function isJsonLintConfig(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const candidate = value;
+    if (typeof candidate.rootDir !== 'string') {
+        return false;
+    }
+    if (!Array.isArray(candidate.ignoredDirectories)) {
+        return false;
+    }
+    if (!Array.isArray(candidate.extensionRuleSets)) {
+        return false;
+    }
+    if (candidate.contentRuleSets !== undefined && !Array.isArray(candidate.contentRuleSets)) {
+        return false;
+    }
+    const extensionRuleSetsValid = candidate.extensionRuleSets.every((ruleSet) => {
+        if (!ruleSet || typeof ruleSet !== 'object') {
+            return false;
+        }
+        const typedRuleSet = ruleSet;
+        if (typeof typedRuleSet.extension !== 'string') {
+            return false;
+        }
+        if (typedRuleSet.folderName !== undefined && typeof typedRuleSet.folderName !== 'string') {
+            return false;
+        }
+        if (!typedRuleSet.groups || typeof typedRuleSet.groups !== 'object') {
+            return false;
+        }
+        const groups = typedRuleSet.groups;
+        const allRulesValid = groups.all === undefined ||
+            (Array.isArray(groups.all) &&
+                groups.all.every((rule) => !!rule &&
+                    typeof rule.description === 'string' &&
+                    typeof rule.pattern === 'string' &&
+                    (rule.flags === undefined || typeof rule.flags === 'string')));
+        const anyRulesValid = groups.any === undefined ||
+            (Array.isArray(groups.any) &&
+                groups.any.every((rule) => !!rule &&
+                    typeof rule.description === 'string' &&
+                    typeof rule.pattern === 'string' &&
+                    (rule.flags === undefined || typeof rule.flags === 'string')));
+        return allRulesValid && anyRulesValid;
+    });
+    if (!extensionRuleSetsValid) {
+        return false;
+    }
+    return (candidate.contentRuleSets ?? []).every((ruleSet) => {
+        if (!ruleSet || typeof ruleSet !== 'object') {
+            return false;
+        }
+        const typedRuleSet = ruleSet;
+        if (typeof typedRuleSet.extension !== 'string') {
+            return false;
+        }
+        if (!isContentTarget(typedRuleSet.target)) {
+            return false;
+        }
+        if (!typedRuleSet.groups || typeof typedRuleSet.groups !== 'object') {
+            return false;
+        }
+        const groups = typedRuleSet.groups;
+        const allRulesValid = groups.all === undefined ||
+            (Array.isArray(groups.all) &&
+                groups.all.every((rule) => !!rule &&
+                    typeof rule.description === 'string' &&
+                    typeof rule.pattern === 'string' &&
+                    (rule.flags === undefined || typeof rule.flags === 'string')));
+        const anyRulesValid = groups.any === undefined ||
+            (Array.isArray(groups.any) &&
+                groups.any.every((rule) => !!rule &&
+                    typeof rule.description === 'string' &&
+                    typeof rule.pattern === 'string' &&
+                    (rule.flags === undefined || typeof rule.flags === 'string')));
+        return allRulesValid && anyRulesValid;
+    });
+}
+function isContentTarget(target) {
+    return target === 'field' || target === 'inputParameter' || target === 'outputParameter';
+}
+function compileRuleGroup(groups, contextRoot) {
+    const allRules = (groups.all ?? []).map((rule, index) => {
+        const flags = rule.flags ?? '';
+        const context = `${contextRoot} group "all" rule #${index + 1}`;
+        return {
+            description: rule.description,
+            source: rule.pattern,
+            flags,
+            pattern: compileRegex(rule.pattern, flags, context)
+        };
+    });
+    const anyRules = (groups.any ?? []).map((rule, index) => {
+        const flags = rule.flags ?? '';
+        const context = `${contextRoot} group "any" rule #${index + 1}`;
+        return {
+            description: rule.description,
+            source: rule.pattern,
+            flags,
+            pattern: compileRegex(rule.pattern, flags, context)
+        };
+    });
+    return {
+        all: allRules.length > 0 ? allRules : undefined,
+        any: anyRules.length > 0 ? anyRules : undefined
+    };
+}
+/**
+ * Validate regex flags for duplicate/unsupported values.
+ *
+ * @param flags - Raw regex flags string.
+ * @param context - Rule context for clear error messages.
+ */
+function validateRegexFlags(flags, context) {
+    const allowedFlags = new Set(['d', 'g', 'i', 'm', 's', 'u', 'v', 'y']);
+    const seen = new Set();
+    for (const flag of flags) {
+        if (!allowedFlags.has(flag)) {
+            throw new Error(`Invalid regex flag in ${context}: "${flag}"`);
+        }
+        if (seen.has(flag)) {
+            throw new Error(`Duplicate regex flag in ${context}: "${flag}"`);
+        }
+        seen.add(flag);
+    }
+}
+/**
+ * Compile regex source and flags into RegExp with helpful error context.
+ *
+ * @param source - Regex source from config.
+ * @param flags - Regex flags from config.
+ * @param context - Rule context for error reporting.
+ * @returns Compiled RegExp.
+ */
+function compileRegex(source, flags, context) {
+    validateRegexFlags(flags, context);
+    try {
+        return new RegExp(source, flags);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown regex error';
+        throw new Error(`Invalid regex in ${context}: pattern="${source}" flags="${flags}". ${message}`, { cause: error });
+    }
+}