hana-linter 0.1.1

package/src/content-lint.ts

@@ -0,0 +1,187 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { LintIssue } from './types/issues';
+import { ContentRuleSet, ContentTarget, RuleDefinition } from './types/rules';
+
+type ExtractedSubject = {
+    readonly type: ContentTarget;
+    readonly name: string;
+};
+
+/**
+ * Run content-based naming lint for a file.
+ *
+ * @param filePath - Candidate file path.
+ * @param contentRuleSets - Configured content rule sets.
+ * @returns List of content-based lint issues.
+ */
+export async function lintFileContent(filePath: string, contentRuleSets: readonly ContentRuleSet[]): Promise<LintIssue[]> {
+    const extension = path.extname(filePath);
+    const matchingRuleSets = contentRuleSets.filter((ruleSet) => ruleSet.extension === '*' || ruleSet.extension === extension);
+
+    if (matchingRuleSets.length === 0) {
+        return [];
+    }
+
+    const fileContent = await fs.readFile(filePath, { encoding: 'utf-8' });
+    const extractedSubjects = extractSubjects(extension, fileContent);
+
+    if (extractedSubjects.length === 0) {
+        return [];
+    }
+
+    const issues: LintIssue[] = [];
+
+    for (const subject of extractedSubjects) {
+        const targetRuleSets = matchingRuleSets.filter((ruleSet) => ruleSet.target === subject.type);
+        if (targetRuleSets.length === 0) {
+            continue;
+        }
+
+        const allRules = targetRuleSets.flatMap((ruleSet) => ruleSet.groups.all ?? []);
+        const anyRules = targetRuleSets.flatMap((ruleSet) => ruleSet.groups.any ?? []);
+
+        if (allRules.length > 0) {
+            issues.push(...evaluateAllRules(filePath, extension, subject, allRules));
+        }
+
+        if (anyRules.length > 0) {
+            issues.push(...evaluateAnyRules(filePath, extension, subject, anyRules));
+        }
+    }
+
+    return issues;
+}
+
+function extractSubjects(extension: string, fileContent: string): ExtractedSubject[] {
+    if (extension === '.hdbtable') {
+        return extractTableFields(fileContent);
+    }
+
+    if (extension === '.hdbprocedure' || extension === '.hdbfunction') {
+        return extractProcedureFunctionParameters(fileContent);
+    }
+
+    return [];
+}
+
+function extractTableFields(fileContent: string): ExtractedSubject[] {
+    const subjects: ExtractedSubject[] = [];
+    const seen = new Set<string>();
+    const lines = fileContent.split(/\r?\n/);
+    const skipKeywords = new Set(['PRIMARY', 'CONSTRAINT', 'UNIQUE', 'FOREIGN', 'CHECK', 'PARTITION', 'INDEX', 'KEY']);
+
+    for (const line of lines) {
+        const trimmedLine = line.trim();
+        if (trimmedLine.length === 0 || trimmedLine.startsWith('--')) {
+            continue;
+        }
+
+        const unquotedMatch = trimmedLine.match(/^([A-Za-z_][A-Za-z0-9_]*)\s+[A-Za-z]/);
+        if (unquotedMatch) {
+            const candidate = unquotedMatch[1];
+            if (!candidate) {
+                continue;
+            }
+
+            if (!skipKeywords.has(candidate.toUpperCase()) && !seen.has(candidate)) {
+                seen.add(candidate);
+                subjects.push({ type: 'field', name: candidate });
+            }
+            continue;
+        }
+
+        const quotedMatch = trimmedLine.match(/^"([A-Za-z_][A-Za-z0-9_]*)"\s+[A-Za-z]/);
+        if (quotedMatch) {
+            const candidate = quotedMatch[1];
+            if (!candidate) {
+                continue;
+            }
+
+            if (!seen.has(candidate)) {
+                seen.add(candidate);
+                subjects.push({ type: 'field', name: candidate });
+            }
+        }
+    }
+
+    return subjects;
+}
+
+function extractProcedureFunctionParameters(fileContent: string): ExtractedSubject[] {
+    const subjects: ExtractedSubject[] = [];
+    const seen = new Set<string>();
+    const parameterRegex = /\b(IN|OUT|INOUT)\s+("?[A-Za-z_][A-Za-z0-9_]*"?)\s+[A-Za-z]/gi;
+
+    let match = parameterRegex.exec(fileContent);
+    while (match) {
+        const mode = match[1];
+        const rawName = match[2];
+
+        if (!mode || !rawName) {
+            match = parameterRegex.exec(fileContent);
+            continue;
+        }
+
+        const normalizedMode = mode.toUpperCase();
+        const normalizedName = rawName.replace(/^"|"$/g, '');
+
+        if ((normalizedMode === 'IN' || normalizedMode === 'INOUT') && !seen.has(`input:${normalizedName}`)) {
+            seen.add(`input:${normalizedName}`);
+            subjects.push({ type: 'inputParameter', name: normalizedName });
+        }
+
+        if ((normalizedMode === 'OUT' || normalizedMode === 'INOUT') && !seen.has(`output:${normalizedName}`)) {
+            seen.add(`output:${normalizedName}`);
+            subjects.push({ type: 'outputParameter', name: normalizedName });
+        }
+
+        match = parameterRegex.exec(fileContent);
+    }
+
+    return subjects;
+}
+
+function evaluateAllRules(filePath: string, extension: string, subject: ExtractedSubject, rules: readonly RuleDefinition[]): LintIssue[] {
+    const issues: LintIssue[] = [];
+
+    for (const rule of rules) {
+        if (!rule.pattern.test(subject.name)) {
+            issues.push({
+                filePath,
+                artifactName: path.parse(filePath).name,
+                extension,
+                subjectType: subject.type,
+                subjectName: subject.name,
+                failedRuleDescription: rule.description,
+                failedPattern: toRegexLiteral(rule)
+            });
+        }
+    }
+
+    return issues;
+}
+
+function evaluateAnyRules(filePath: string, extension: string, subject: ExtractedSubject, rules: readonly RuleDefinition[]): LintIssue[] {
+    const hasAtLeastOneMatch = rules.some((rule) => rule.pattern.test(subject.name));
+
+    if (hasAtLeastOneMatch) {
+        return [];
+    }
+
+    return [
+        {
+            filePath,
+            artifactName: path.parse(filePath).name,
+            extension,
+            subjectType: subject.type,
+            subjectName: subject.name,
+            failedRuleDescription: 'At least one OR-group rule must match: ' + rules.map((rule) => rule.description).join(' | '),
+            failedPattern: rules.map(toRegexLiteral).join(' OR ')
+        }
+    ];
+}
+
+function toRegexLiteral(rule: RuleDefinition): string {
+    return `/${rule.source}/${rule.flags}`;
+}

package/src/files.ts

@@ -0,0 +1,84 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { CliInput } from './types/cli';
+import { LintConfig } from './types/config';
+
+/**
+ * Resolve files to validate:
+ * - If CLI files are provided: use only existing files from that list.
+ * - If none are provided: run full scan from rootDir.
+ *
+ * @param config - Lint configuration.
+ * @param cliInput - Parsed CLI input.
+ * @returns List of file paths to validate.
+ */
+export async function resolveFilesToValidate(config: LintConfig, cliInput: CliInput): Promise<string[]> {
+    if (cliInput.files.length > 0) {
+        const existingChecks = await Promise.all(
+            cliInput.files.map(async (filePath) => ({
+                filePath,
+                exists: await isExistingFile(filePath)
+            }))
+        );
+
+        return existingChecks.filter((item) => item.exists).map((item) => path.normalize(item.filePath));
+    }
+
+    const rootExists = await fs
+        .access(config.rootDir)
+        .then(() => true)
+        .catch(() => false);
+
+    if (!rootExists) {
+        throw new Error(`Configured root directory does not exist: "${config.rootDir}"`);
+    }
+
+    return collectFiles(config.rootDir, config.ignoredDirectories);
+}
+
+/**
+ * Check if a path exists and is a regular file.
+ *
+ * @param filePath - Path to validate.
+ * @returns True if path exists and is a file.
+ */
+async function isExistingFile(filePath: string): Promise<boolean> {
+    try {
+        const stat = await fs.stat(filePath);
+        return stat.isFile();
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Recursively collect all files from a directory while skipping ignored folders.
+ *
+ * @param directoryPath - Absolute or relative folder path.
+ * @param ignoredDirectories - Directory names to skip.
+ * @returns List of full file paths.
+ */
+async function collectFiles(directoryPath: string, ignoredDirectories: readonly string[]): Promise<string[]> {
+    const entries = await fs.readdir(directoryPath, { withFileTypes: true });
+
+    const collected = await Promise.all(
+        entries.map(async (entry) => {
+            const fullPath = path.join(directoryPath, entry.name);
+
+            if (entry.isDirectory()) {
+                if (ignoredDirectories.includes(entry.name)) {
+                    return [];
+                }
+                return collectFiles(fullPath, ignoredDirectories);
+            }
+
+            if (entry.isFile()) {
+                return [fullPath];
+            }
+
+            return [];
+        })
+    );
+
+    return collected.flat();
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+import { parseCliInput, runInit } from './cli';
+import { readJsonConfig, toLintConfig } from './config';
+import { resolveFilesToValidate } from './files';
+import { runLint } from './lint';
+import { printReport } from './report';
+
+/**
+ * Application entry point.
+ */
+async function main(): Promise<void> {
+    const cliInput = parseCliInput();
+
+    if (cliInput.command === 'init') {
+        await runInit(cliInput.force);
+        return;
+    }
+
+    const jsonConfig = await readJsonConfig(cliInput.configPath);
+    const config = toLintConfig(jsonConfig);
+
+    const filesToValidate = await resolveFilesToValidate(config, cliInput);
+    const issues = await runLint(config, filesToValidate);
+
+    printReport(issues, filesToValidate);
+
+    if (issues.length > 0) {
+        process.exitCode = 1;
+    }
+}
+
+void main().catch((error: unknown) => {
+    const message = error instanceof Error ? error.message : 'Unknown error occurred';
+    console.error(`❌ HANA naming lint crashed: ${message}`);
+    process.exitCode = 1;
+});

package/src/lint.ts

@@ -0,0 +1,222 @@
+import path from 'node:path';
+import { lintFileContent } from './content-lint';
+import { LintIssue } from './types/issues';
+import { LintConfig } from './types/config';
+import { ExtensionRuleSet, RuleDefinition } from './types/rules';
+
+/**
+ * Run naming lint and return all discovered issues.
+ *
+ * @param config - Lint configuration.
+ * @param filesToValidate - File paths to validate.
+ * @returns All naming violations.
+ */
+export async function runLint(config: LintConfig, filesToValidate: readonly string[]): Promise<LintIssue[]> {
+    const issues: LintIssue[] = [];
+
+    for (const filePath of filesToValidate) {
+        const fileIssues = validateFileName(filePath, config.extensionRuleSets, config.rootDir);
+        issues.push(...fileIssues);
+
+        if (config.contentRuleSets.length > 0) {
+            const contentIssues = await lintFileContent(filePath, config.contentRuleSets);
+            issues.push(...contentIssues);
+        }
+    }
+
+    return issues;
+}
+
+/**
+ * Validate a single file against configured rule groups for its extension.
+ *
+ * @param filePath - Full file path.
+ * @param extensionRuleSets - Configured extension rule sets.
+ * @param rootDir - Configured root directory.
+ * @returns List of lint issues.
+ */
+function validateFileName(filePath: string, extensionRuleSets: readonly ExtensionRuleSet[], rootDir: string): LintIssue[] {
+    const extension = path.extname(filePath);
+    const matchedRuleSets = findRuleSetsForExtension(extension, extensionRuleSets);
+    const ruleSet = mergeRuleSets(extension, matchedRuleSets);
+
+    if (!ruleSet) {
+        return [];
+    }
+
+    const artifactName = getArtifactNameFromFilePath(filePath);
+    const issues: LintIssue[] = [];
+
+    if (ruleSet.folderName && !isFileInRequiredFolder(filePath, rootDir, ruleSet.folderName)) {
+        issues.push({
+            filePath,
+            artifactName,
+            extension,
+            subjectType: 'artifact',
+            subjectName: artifactName,
+            failedRuleDescription: `File must be located in folder "${ruleSet.folderName}" under configured rootDir`,
+            failedPattern: `folder:${ruleSet.folderName}`
+        });
+    }
+
+    const allRules = ruleSet.groups.all ?? [];
+    const anyRules = ruleSet.groups.any ?? [];
+
+    if (allRules.length > 0) {
+        issues.push(...evaluateAllRules(filePath, artifactName, extension, allRules));
+    }
+
+    if (anyRules.length > 0) {
+        issues.push(...evaluateAnyRules(filePath, artifactName, extension, anyRules));
+    }
+
+    return issues;
+}
+
+/**
+ * Extract artifact name from file path.
+ *
+ * @param filePath - Full file path.
+ * @returns Artifact name without extension.
+ */
+function getArtifactNameFromFilePath(filePath: string): string {
+    const parsed = path.parse(filePath);
+    return parsed.name;
+}
+
+/**
+ * Resolve matching rule sets for a file extension.
+ *
+ * @param extension - File extension.
+ * @param extensionRuleSets - Configured extension rule sets.
+ * @returns Matching extension rule sets.
+ */
+function findRuleSetsForExtension(extension: string, extensionRuleSets: readonly ExtensionRuleSet[]): ExtensionRuleSet[] {
+    return extensionRuleSets.filter((ruleSet) => ruleSet.extension === '*' || ruleSet.extension === extension);
+}
+
+/**
+ * Merge multiple rule sets into a single effective set.
+ *
+ * @param extension - File extension.
+ * @param ruleSets - Matching rule sets for extension.
+ * @returns Merged rule set or undefined when no rules apply.
+ */
+function mergeRuleSets(extension: string, ruleSets: readonly ExtensionRuleSet[]): ExtensionRuleSet | undefined {
+    if (ruleSets.length === 0) {
+        return undefined;
+    }
+
+    const specificRuleSets = ruleSets.filter((ruleSet) => ruleSet.extension === extension);
+    const wildcardRuleSets = ruleSets.filter((ruleSet) => ruleSet.extension === '*');
+
+    const specificFolderName = specificRuleSets.find((ruleSet) => ruleSet.folderName !== undefined)?.folderName;
+    const wildcardFolderName = wildcardRuleSets.find((ruleSet) => ruleSet.folderName !== undefined)?.folderName;
+
+    const allRules = ruleSets.flatMap((ruleSet) => ruleSet.groups.all ?? []);
+    const anyRules = ruleSets.flatMap((ruleSet) => ruleSet.groups.any ?? []);
+
+    return {
+        extension,
+        folderName: specificFolderName ?? wildcardFolderName,
+        groups: {
+            all: allRules.length > 0 ? allRules : undefined,
+            any: anyRules.length > 0 ? anyRules : undefined
+        }
+    };
+}
+
+/**
+ * Check whether a file is located under a target folder name within rootDir.
+ *
+ * @param filePath - Candidate file path.
+ * @param rootDir - Configured root directory.
+ * @param requiredFolderName - Folder name to enforce.
+ * @returns True when file is under rootDir and contained in required folder.
+ */
+function isFileInRequiredFolder(filePath: string, rootDir: string, requiredFolderName: string): boolean {
+    const absoluteRootDir = path.resolve(rootDir);
+    const absoluteFilePath = path.resolve(filePath);
+    const relativeToRoot = path.relative(absoluteRootDir, absoluteFilePath);
+
+    // Files outside rootDir are never valid for folder enforcement.
+    if (relativeToRoot.startsWith('..') || path.isAbsolute(relativeToRoot)) {
+        return false;
+    }
+
+    const parentDirectory = path.dirname(relativeToRoot);
+    if (parentDirectory === '.' || parentDirectory.length === 0) {
+        return false;
+    }
+
+    const folderSegments = parentDirectory.split(path.sep);
+    return folderSegments.includes(requiredFolderName);
+}
+
+/**
+ * Convert a rule to displayable regex literal text.
+ *
+ * @param rule - Runtime rule.
+ * @returns Regex literal-like string.
+ */
+function toRegexLiteral(rule: RuleDefinition): string {
+    return `/${rule.source}/${rule.flags}`;
+}
+
+/**
+ * Build lint issues for failed AND-rules.
+ *
+ * @param filePath - File path.
+ * @param artifactName - Artifact name.
+ * @param extension - Artifact extension.
+ * @param rules - AND-rules list.
+ * @returns Lint issues for failed rules.
+ */
+function evaluateAllRules(filePath: string, artifactName: string, extension: string, rules: readonly RuleDefinition[]): LintIssue[] {
+    const issues: LintIssue[] = [];
+
+    for (const rule of rules) {
+        if (!rule.pattern.test(artifactName)) {
+            issues.push({
+                filePath,
+                artifactName,
+                extension,
+                subjectType: 'artifact',
+                subjectName: artifactName,
+                failedRuleDescription: rule.description,
+                failedPattern: toRegexLiteral(rule)
+            });
+        }
+    }
+
+    return issues;
+}
+
+/**
+ * Build lint issue for failed OR-group.
+ *
+ * @param filePath - File path.
+ * @param artifactName - Artifact name.
+ * @param extension - Artifact extension.
+ * @param rules - OR-rules list.
+ * @returns Single lint issue if OR-group fails; otherwise empty list.
+ */
+function evaluateAnyRules(filePath: string, artifactName: string, extension: string, rules: readonly RuleDefinition[]): LintIssue[] {
+    const hasAtLeastOneMatch = rules.some((rule) => rule.pattern.test(artifactName));
+
+    if (hasAtLeastOneMatch) {
+        return [];
+    }
+
+    return [
+        {
+            filePath,
+            artifactName,
+            extension,
+            subjectType: 'artifact',
+            subjectName: artifactName,
+            failedRuleDescription: 'At least one OR-group rule must match: ' + rules.map((rule) => rule.description).join(' | '),
+            failedPattern: rules.map(toRegexLiteral).join(' OR ')
+        }
+    ];
+}

package/src/report.ts

@@ -0,0 +1,29 @@
+import { LintIssue } from './types/issues';
+
+/**
+ * Print lint result report to stdout/stderr.
+ *
+ * @param issues - Found naming violations.
+ * @param filesToValidate - Number of candidate files processed.
+ */
+export function printReport(issues: readonly LintIssue[], filesToValidate: readonly string[]): void {
+    if (issues.length === 0) {
+        console.info(`✅ HANA naming lint passed. Checked ${filesToValidate.length} file(s).`);
+        return;
+    }
+
+    console.error(`❌ HANA naming lint failed. Violations: ${issues.length}`);
+    console.error('');
+
+    for (const issue of issues) {
+        console.error(`- File: ${issue.filePath}`);
+        console.error(`  Artifact: ${issue.artifactName}`);
+        if (issue.subjectType && issue.subjectName) {
+            console.error(`  Subject: ${issue.subjectType} (${issue.subjectName})`);
+        }
+        console.error(`  Type: ${issue.extension}`);
+        console.error(`  Failed rule: ${issue.failedRuleDescription}`);
+        console.error(`  Expected regex: ${issue.failedPattern}`);
+        console.error('');
+    }
+}

package/src/types/cli.ts

@@ -0,0 +1,21 @@
+export type CliCommand = 'lint' | 'init';
+
+export type CliInput = {
+    /**
+     * CLI command mode.
+     */
+    readonly command: CliCommand;
+    /**
+     * Files passed via CLI.
+     * Empty list means full-scan mode.
+     */
+    readonly files: readonly string[];
+    /**
+     * Config path override.
+     */
+    readonly configPath: string;
+    /**
+     * Allow overwriting existing config in init mode.
+     */
+    readonly force: boolean;
+};

package/src/types/config.ts

@@ -0,0 +1,20 @@
+import { ContentRuleSet, ExtensionRuleSet } from './rules';
+
+export type LintConfig = {
+    /**
+     * Base folder to scan in full-scan mode.
+     */
+    readonly rootDir: string;
+    /**
+     * Directory names to skip during traversal.
+     */
+    readonly ignoredDirectories: readonly string[];
+    /**
+     * Compiled rule sets.
+     */
+    readonly extensionRuleSets: readonly ExtensionRuleSet[];
+    /**
+     * Optional compiled content rule sets.
+     */
+    readonly contentRuleSets: readonly ContentRuleSet[];
+};

package/src/types/issues.ts

@@ -0,0 +1,9 @@
+export type LintIssue = {
+    readonly filePath: string;
+    readonly artifactName: string;
+    readonly extension: string;
+    readonly subjectType?: 'artifact' | 'field' | 'inputParameter' | 'outputParameter';
+    readonly subjectName?: string;
+    readonly failedRuleDescription: string;
+    readonly failedPattern: string;
+};