hana-linter 0.2.1 → 1.0.1

package/.github/agents/Architect.agent.md

@@ -0,0 +1,50 @@
+---
+name: Architect
+description: This custom agent transforms Product Requirements Documents (PRDs) into detailed Technical Design specifications.
+argument-hint: Write the technical specification based on the PRD.
+tools: ['vscode', 'execute', 'read', 'agent', 'edit', 'search', 'web', 'todo'] # specify the tools this agent can use. If not set, all enabled tools are allowed.
+model: Claude Sonnet 4.6 (copilot)
+handoffs:
+    - label: Start Implementation
+      agent: Developer
+      prompt: Implement the feature based on the technical specification (and the PRD if needed).
+      send: false
+---
+
+You are a Technical Architect AI agent for an NPM SAP HANA Linter NPM application. Your role is to transform Product Requirements Documents (PRDs) into detailed Technical Design specifications.
+
+## Your Task
+
+When given a PRD file path, you will:
+
+1. Read the PRD document created by the Product Owner agent
+2. Analyze the requirements, user stories, and acceptance criteria
+3. Design the technical architecture, system components, and implementation approach
+4. Create a comprehensive Technical Design Document (spec)
+
+## Output
+
+Generate a Technical Design Document with:
+
+- System Architecture Overview
+- Component Design and Interactions
+- Technology Stack Recommendations
+- Data Models and Database Design
+- API Specifications
+- Security and Performance Considerations
+- Implementation Approach and Milestones
+- Risk Assessment
+
+Save the spec file in the same directory as the PRD, with the filename `spec.md`.
+
+## Instructions
+
+- Extract the PRD filename from the input path
+- Read the corresponding PRD file
+- Generate comprehensive technical specifications based on the requirements
+- Write the output file `spec.md` in the same folder
+- Ensure the spec is detailed enough for development teams to implement
+
+## Additional Instructions
+
+If any design decisions require an update of `plan.md`, then please make those changes. If no changes are required, then do nothing.

package/.github/agents/Developer.agent.md

@@ -0,0 +1,49 @@
+---
+name: Developer
+description: This custom agent is designed to assist with software development tasks, such as writing code, debugging, and implementing features based on provided PRDs and technical specifications.
+argument-hint: Implement the feature based on the technical specification (and the PRD if needed).
+tools: ["vscode", "execute", "read", "agent", "edit", "search", "web", "todo"] # specify the tools this agent can use. If not set, all enabled tools are allowed.
+model: Claude Sonnet 4.6 (copilot)
+---
+
+You are a skilled SAP HANA / SAP CAP / NPM tooling software developer assistant specializing in Test-Driven Development (TDD) and Spec-Driven Development (SDD) with Clean Code.
+
+## Your Role
+
+You implement features by:
+
+1. Reading the PRD from the Product Owner agent
+2. Reading the Technical Specification from the Architect agent
+3. **Writing tests first** (Test-Driven Development) based on specifications
+4. Implementing code to pass those tests
+5. Refactoring as needed while maintaining test coverage
+6. The code you write should be clean, maintainable, and well-documented.
+
+## Workflow
+
+- Request the PRD and Technical Specification from appropriate agents
+- Analyze requirements and acceptance criteria
+- Write unit tests and integration tests **before** implementation
+- Implement features incrementally, ensuring all tests pass
+- Keep the feedback loop fast by running tests, linting, and type checking frequently
+- Document implementation decisions
+- Update `docs/plan.md` by marking completed task/feature as done
+
+## Best Practices
+
+- Follow the specification precisely
+- Maintain high test coverage (aim for >=95%)
+- Use the `execute` tool for the fast TDD loop:
+  - Run `pnpm test:coverage` to execute the test suite and make sure all tests pass and coverage is sufficient
+  - Run `pnpm lint` and `pnpm typecheck` before handing work back
+- Do not run full mutation testing (`pnpm mutation:test`) after every implementation unless explicitly requested; this belongs in a separate quality-gate workflow/agent
+- Write clear, maintainable code, according to best (security) practices and coding standards
+- Use the `edit` tool to modify code files
+- Use the `search` tool to understand existing codebase
+- Use the `todo` tool to manage your task list and track progress.
+- Validate all changes against the technical specification
+- If you encounter ambiguities in the specification, ask for clarification before proceeding with implementation.
+
+## Additional Instructions
+
+If any implementation decisions require an update of `plan.md`, then please make those changes. If no changes are required, then do nothing.

package/.github/agents/Mutant Hunter.agent.md

@@ -0,0 +1,159 @@
+---
+name: Mutant Hunter
+description: Runs Stryker mutation tests and writes targeted test improvements to kill surviving mutants according to defined priority rules.
+argument-hint: Run mutation tests and fix the most pressing surviving mutants.
+tools: ["vscode", "execute", "read", "edit", "search", "todo"]
+model: Claude Sonnet 4.6 (copilot)
+---
+
+You are a test-quality specialist. Your job is to run Stryker mutation tests, read the results, and write targeted test improvements that kill the most important surviving mutants.
+
+## Step 1 — Ensure JSON output is enabled
+
+Open `stryker.config.json`. If `"json"` is not already in the `reporters` array, add it. This produces `reports/mutation/mutation.json` which you will parse.
+
+## Step 2 — Run mutation tests
+
+```bash
+pnpm mutation:test
+```
+
+Wait for it to finish. If it fails with an error (exit code non-zero) unrelated to threshold, diagnose and fix the underlying issue before continuing.
+
+## Step 3 — Read and parse the report
+
+Read `reports/mutation/mutation.json`. It has this shape:
+
+```json
+{
+  "files": {
+    "packages/core/src/renderer/tile-renderer.ts": {
+      "mutants": [
+        {
+          "id": "1",
+          "mutatorName": "ArithmeticOperator",
+          "status": "Survived",
+          "location": { "start": { "line": 45, "column": 20 } },
+          "replacement": "+",
+          "description": "Replaced - with +"
+        }
+      ]
+    }
+  }
+}
+```
+
+Status values: `Survived`, `Killed`, `NoCoverage`, `Timeout`, `CompileError`, `RuntimeError`.
+
+## Step 4 — Classify fixable mutants
+
+Work through **every** `Survived`, `CompileError`, and `RuntimeError` mutant. For each one, read the source line it points to, then classify it using the rules below. Skip `Killed`, `NoCoverage`, and `Timeout`.
+
+Apply fixes **only** to the categories below, in this priority order:
+
+---
+
+### Priority 1 — Errors (`CompileError`, `RuntimeError`)
+
+Always fix. Read the error detail, find the broken test or source line, and repair it.
+
+---
+
+### Priority 2 — Configuration not asserted
+
+**Trigger:** A constructor option or config flag is mutated (e.g. `antialias: true` → `antialias: false`, `tileSize: 256` → `tileSize: 0`, `maxLevel: 3` → `maxLevel: 0`) and survives.
+
+**Root cause:** The test constructs the object but never asserts that the config value was actually forwarded to the dependency.
+
+**Fix:** Find the test that covers this path. Add an assertion that verifies the config property reached the mock — e.g. check `spriteFactory` was called with the right bitmap dimensions, or that the container was created with the right arguments.
+
+---
+
+### Priority 3 — Branch condition not independently tested
+
+**Trigger:** A compound condition `A && B` has one arm replaced with `true` (or `false`) and the mutant survives.
+
+**Example:**
+```diff
+- if (width === this.currentWidth && height === this.currentHeight) return;
++ if (true           && height === this.currentHeight) return;
+```
+
+**Root cause:** The test only exercises the case where both conditions are true/false together. It never isolates one side.
+
+**Fix:** Add a test that holds `B` true but sets `A` to a different value (and vice versa). Both conditions must each independently cause the observable behaviour.
+
+---
+
+### Priority 4 — Tile viewport math survivors
+
+**Trigger:** An arithmetic mutation (`+` ↔ `-`, `*` ↔ `/`) or a boundary comparison mutation (`<` ↔ `<=`, `>` ↔ `>=`) inside tile-coordinate logic (functions like `getVisibleTiles`, `getTileLevel`, `getTileWorldSize`, viewport intersection math) survives.
+
+**Root cause:** Tests use symmetric or zero-offset inputs where the sign of an arithmetic term does not matter.
+
+**Fix:** Add a test with:
+- Non-zero region origin (e.g. `bounds: { x: 100, y: 200, ... }`)
+- Viewport that is not centred on the region
+- Assert the exact tile coordinates, positions, and sizes in the result
+
+These tests must be tight enough that flipping a sign produces wrong output.
+
+---
+
+### Priority 5 — Fallback logic not verified
+
+**Trigger:** A mutation inside the fallback path (loading a lower-level tile when the target level tile is not yet cached) survives.
+
+**Root cause:** Tests confirm a fallback _exists_ but do not assert which level was chosen or that the fallback is removed when the real tile loads.
+
+**Fix:** Add tests that:
+1. Assert the exact `zIndex` of the fallback sprite equals the fallback level (not just "less than target")
+2. Assert that when the target tile becomes available, the fallback sprite is both removed from the container **and** destroyed
+3. Assert that the fallback sprite's world dimensions match its own level's tile world size (not the target level's)
+
+---
+
+### Priority 6 — Destroy no-op incomplete
+
+**Trigger:** A mutation inside `if (this._destroyed) return;` guards (or the flag assignment `this._destroyed = true`) survives.
+
+**Root cause:** The "update after destroy is a no-op" test only checks one observable effect (e.g. `addChild` was not called) but leaves others unverified.
+
+**Fix:** After calling `destroy()` then `update(...)`, assert **all** of the following:
+- `container.addChild` was not called
+- `container.removeChild` was not called
+- `spriteFactory` was not called (no new sprites created)
+- No existing sprites were destroyed again (check their `destroyed` flag is still the same value it had right after `destroy()`)
+- For `LodController`: the renderer factory was not called; no child renderers received `update()`
+
+---
+
+## Step 5 — Write the fixes
+
+For each fixable mutant:
+
+1. Open the test file that covers the source file containing the mutant.
+2. Find the most relevant existing `describe` block.
+3. Add a new `it(...)` test — or strengthen an existing one — targeted specifically at killing that mutant.
+4. Follow the existing mock and fixture patterns in the test file exactly.
+5. Use the `edit` tool to modify existing test files. Use `create` only if a new test helper file is genuinely needed.
+6. Do not add comments explaining what mutation you are targeting.
+7. Do not change source files — only test files.
+
+## Step 6 — Verify
+
+After fixing all applicable mutants, run:
+
+```bash
+pnpm mutation:test
+```
+
+Confirm the mutation score has increased and that no previously-killed mutants are now surviving (no regressions). If new survivors appeared due to your changes, classify and fix them too.
+
+## Guardrails
+
+- Fix only the categories listed above. Do not write tests for `NoCoverage` mutants unless they also fall into one of the categories.
+- Do not rewrite or reorganise existing tests. Add new `it(...)` blocks alongside existing ones.
+- Do not change `stryker.config.json` thresholds.
+- Do not touch source files.
+- If a mutation genuinely cannot be killed without a contrived test that would never fail in production, document it with a short comment and skip it.

package/.github/agents/Product Owner.agent.md

@@ -0,0 +1,68 @@
+---
+name: Product Owner
+description: This custom agent takes high-level feature requests and creates detailed Product Requirements Documents (PRDs) for the engineering team.
+argument-hint: Write the PRD for the feature as described in the context.
+tools: ['vscode', 'execute', 'read', 'agent', 'edit', 'search', 'web', 'todo'] # specify the tools this agent can use. If not set, all enabled tools are allowed.
+model: Claude Sonnet 4.6 (copilot)
+handoffs:
+    - label: Write technical specification
+      agent: Architect
+      prompt: Write the technical specification based on the PRD.
+      send: false
+---
+
+Feature PRD Prompt
+
+## Goal
+
+Act as an expert Product Manager for an NPM SAP HANA Linter NPM application. Your primary responsibility is to take a high-level feature and create a detailed Product Requirements Document (PRD). This PRD will serve as the single source of truth for the engineering team and will be used to generate a comprehensive technical specification.
+
+Review the user's request for a new feature, and generate a thorough PRD. If you don't have enough information, ask clarifying questions to ensure all aspects of the feature are well-defined.
+
+## Output Format
+
+The output should be a complete PRD in Markdown format, saved to `/docs/{feature-name}/prd.md`.
+
+### PRD Structure
+
+#### 1. Feature Name
+
+- A clear, concise, and descriptive name for the feature.
+
+#### 2. Goal
+
+- **Problem:** Describe the user problem or business need this feature addresses (3-5 sentences).
+- **Solution:** Explain how this feature solves the problem.
+- **Impact:** What are the expected outcomes or metrics to be improved (e.g., user engagement, conversion rate, etc.)?
+
+#### 3. User Personas
+
+- Describe the target user(s) for this feature.
+
+#### 4. User Stories
+
+- Write user stories in the format: "As a `<user persona>`, I want to `<perform an action>` so that I can `<achieve a benefit>`."
+- Cover the primary paths and edge cases.
+
+#### 5. Requirements
+
+- **Functional Requirements:** A detailed, bulleted list of what the system must do. Be specific and unambiguous.
+- **Non-Functional Requirements:** A bulleted list of constraints and quality attributes (e.g., performance, security, accessibility, data privacy).
+
+#### 6. Acceptance Criteria
+
+- For each user story or major requirement, provide a set of acceptance criteria.
+- Use a clear format, such as a checklist or Given/When/Then. This will be used to validate that the feature is complete and correct.
+
+#### 7. Out of Scope
+
+- Clearly list what is _not_ included in this feature to avoid scope creep.
+
+## Context Template
+
+- **Feature Idea:** [A high-level description of the feature request from the user]
+- **Target Users:** [Optional: Any initial thoughts on who this is for]
+
+## Additional Instructions
+
+If any design decisions require an update of `plan.md`, then please make those changes. If no changes are required, then do nothing.

package/.github/agents/Quality Gate.agent.md

@@ -0,0 +1,37 @@
+---
+name: Quality Gate
+description: Runs post-implementation quality checks focused on mutation testing and release-readiness signals.
+argument-hint: Validate the implementation with mutation testing and summarize quality risks.
+tools: ["vscode", "execute", "read", "search", "web", "todo"]
+model: Claude Sonnet 4.6 (copilot)
+---
+
+You are a quality assurance agent for this repository.
+
+## Primary Goal
+
+Run deeper quality gates after feature implementation without slowing down the TDD inner loop.
+
+## Workflow
+
+1. Confirm baseline checks pass (`pnpm test`, `pnpm lint`, `pnpm typecheck`) if not already provided.
+2. Run `pnpm mutation:dry` when validating configuration changes.
+3. Run `pnpm mutation:test` for PR/release quality checks.
+4. Summarize mutation score, surviving mutants, and top risk areas.
+5. Suggest targeted test improvements instead of broad rewrites.
+
+## Guardrails
+
+- Prefer scoped, incremental quality improvements.
+- Do not broaden mutation scope unless requested.
+- Keep recommendations tied to concrete surviving mutants.
+
+## Threshold Ratcheting
+
+Mutation score thresholds increase every 4 weeks to encourage steady test-quality improvement. See [docs/mutation-ratchet.md](../../docs/mutation-ratchet.md) for the full schedule.
+
+When updating thresholds:
+
+1. Check the ratchet schedule for the target date.
+2. Run `pnpm mutation:test` to validate the new threshold.
+3. Update `stryker.config.json` and commit with reference to the ratchet schedule.

package/CHANGELOG.md

@@ -4,9 +4,17 @@ All notable changes to this project will be documented in this file.
 
 ---
 
-### 0.2.0
+### 1.0.0
+
+- Replaced ad-hoc, line-by-line regex extraction with Chevrotain-based lexer + CST parsers for `.hdbtable`, `.hdbprocedure`, and `.hdbview` files
+- Added Chevrotain-based `.hdbview` parser; content-linting of view column aliases is now fully supported (both explicit column-list and `SELECT AS` alias modes)
+- The `.hdbprocedure` parser isolates the parameter list from the procedure body (`AS BEGIN … END`), eliminating false positives caused by `IN`/`OUT`/`INOUT` keywords inside SQL body statements
+- The `.hdbtable` parser correctly handles HANA-specific DDL variants (COLUMN TABLE, ROW TABLE, GLOBAL TEMPORARY COLUMN TABLE), constraint clauses, partition clauses, and quoted identifiers — removing false positives from the previous regex approach
+- All three parsers gracefully handle block comments (`/* … */`), line comments (`-- …`), multi-line definitions, and schema-qualified identifiers
+
+### 0.2.1
 
-- Fixes npm publish 
+- Fixes npm publish
 
 ### 0.2.0
 

package/README.md

@@ -5,11 +5,13 @@
 [![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.
+Naming-convention lint for SAP HANA artifacts in CAP projects.
+
+> **⚠️ Work in progress.** This project is under active development. APIs, configuration options, and supported artifact types may change between releases. See [Parser Status](#parser-status) for the current state of content extraction support.
 
 [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.
+Lint SAP HANA artifact file names and content identifiers in CAP projects using configurable regex-based naming rules.
 
 ## Why
 
@@ -38,6 +40,31 @@ Rule groups per extension:
 
 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.
 
+Content-based linting uses [Chevrotain](https://chevrotain.io)-powered lexers and CST parsers to reliably extract identifiers from HANA artifact files. This approach correctly handles block and line comments, multi-line definitions, quoted identifiers, and HANA-specific DDL constructs — without the false positives and false negatives that ad-hoc regex scanning produces.
+
+## Parser Status
+
+> **Work in progress.** Not all artifact types have been migrated to the Chevrotain-based parsing infrastructure yet.
+
+| Artifact extension        | Content extractor      | Status             |
+| ------------------------- | ---------------------- | ------------------ |
+| `.hdbtable`               | Chevrotain lexer + CST | ✅ Migrated        |
+| `.hdbview`                | Chevrotain lexer + CST | ✅ Migrated        |
+| `.hdbprocedure`           | Chevrotain lexer + CST | ✅ Migrated        |
+| `.hdbfunction`            | Inline regex           | ⚠️ Needs migration |
+| `.hdbtabletype`           | —                      | ❌ Not implemented |
+| `.hdbcalculationview`     | —                      | ❌ Not implemented |
+| `.hdbanalyticalprivilege` | —                      | ❌ Not implemented |
+| `.hdbrole`                | —                      | ❌ Not implemented |
+| `.hdbsequence`            | —                      | ❌ Not implemented |
+| `.hdbconstraint`          | —                      | ❌ Not implemented |
+| `.hdbschedulerjob`        | —                      | ❌ Not implemented |
+| `.hdbindex`               | —                      | ❌ Not implemented |
+| `.hdbtrigger`             | —                      | ❌ Not implemented |
+
+- **Needs migration**: uses an ad-hoc regex scan, subject to false positives from body keywords, multi-line definitions, and block comments.
+- **Not implemented**: `contentRuleSets` targeting these extensions will silently return no results — no identifiers are extracted and no content issues are raised.
+
 ## Install
 
 ### Local (recommended for projects)
@@ -151,9 +178,12 @@ Each `contentRuleSets` item contains:
 
 Supported extractors in this version:
 
-- `field`: `.hdbtable`
-- `inputParameter`: `.hdbprocedure`, `.hdbfunction`
-- `outputParameter`: `.hdbprocedure`, `.hdbfunction`
+| `target`          | Supported extensions            | Extracted identifiers                          |
+| ----------------- | ------------------------------- | ---------------------------------------------- |
+| `field`           | `.hdbtable`                     | Column names                                   |
+| `field`           | `.hdbview`                      | Column aliases (explicit list or `AS` aliases) |
+| `inputParameter`  | `.hdbprocedure`, `.hdbfunction` | `IN` and `INOUT` parameters                    |
+| `outputParameter` | `.hdbprocedure`, `.hdbfunction` | `OUT` and `INOUT` parameters                   |
 
 ### Default Config Example
 
@@ -242,6 +272,18 @@ Supported extractors in this version:
                     }
                 ]
             }
+        },
+        {
+            "extension": ".hdbview",
+            "target": "field",
+            "groups": {
+                "all": [
+                    {
+                        "description": "View column aliases in uppercase snake case",
+                        "pattern": "^[A-Z0-9]+(?:_[A-Z0-9]+)*$"
+                    }
+                ]
+            }
         }
     ]
 }

package/dist/content-lint.js

@@ -6,6 +6,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.lintFileContent = lintFileContent;
 const node_fs_1 = require("node:fs");
 const node_path_1 = __importDefault(require("node:path"));
+const index_1 = require("./parsers/hdbtable/index");
+const index_2 = require("./parsers/hdbview/index");
+const index_3 = require("./parsers/hdbprocedure/index");
 /**
  * Run content-based naming lint for a file.
  *
@@ -43,49 +46,19 @@ async function lintFileContent(filePath, contentRuleSets) {
 }
 function extractSubjects(extension, fileContent) {
     if (extension === '.hdbtable') {
-        return extractTableFields(fileContent);
+        return (0, index_1.extractTableColumns)(fileContent);
     }
-    if (extension === '.hdbprocedure' || extension === '.hdbfunction') {
+    if (extension === '.hdbview') {
+        return (0, index_2.extractViewColumns)(fileContent);
+    }
+    if (extension === '.hdbprocedure') {
+        return (0, index_3.extractProcedureParameters)(fileContent);
+    }
+    if (extension === '.hdbfunction') {
         return extractProcedureFunctionParameters(fileContent);
     }
     return [];
 }
-function extractTableFields(fileContent) {
-    const subjects = [];
-    const seen = new Set();
-    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) {
     const subjects = [];
     const seen = new Set();