@enigmax/linter

@enigmax/linter

A small, fast linter and security auditor that enforces the Ciphera code style and flags hardcoded secrets. JavaScript/TypeScript is parsed with the TypeScript compiler API, so its style checks are AST-accurate rather than regex guesses; Python, Rust, and Prisma get the language-agnostic checks (file hygiene, blank-line collapsing, and secret detection) with lightweight per-language lexing so blanks inside docstrings, block comments, and multi-line strings are left alone.

Container formats - Jupyter notebooks (.ipynb), Astro (.astro), and Vue/Svelte single-file components (.vue, .svelte) - are understood structurally: the embedded code is extracted and linted as its real language, and the wrapper (JSON, HTML) is never fed to the rules. Violations are mapped back to the physical line in the original file.

It is meant to be run on demand - by a developer, by an agent as a self-check, or wired into a project's scripts/CI - not as an always-on background process.

Languages

The AST-based Ciphera style rules (length-sorted imports, double quotes, template literals, semicolons, URL imports) are JavaScript/TypeScript-only by design: they encode TS idioms and would misfire on other grammars (for example, Rust 'a' char literals or Python's idiomatic single quotes).

Container formats (embedded code)

Only the code regions are linted - the surrounding JSON or HTML template is never checked. The file-boundary part of file-hygiene (final newline, leading/trailing blank line) is skipped for embedded fragments, since the container owns the file's physical shape; trailing whitespace inside the code is still flagged. Every violation's line number refers to the physical line in the original file.

Usage

# lint the current directory
npx @enigmax/linter

# lint specific paths
npx @enigmax/linter src test

# only the security audit, or only style
npx @enigmax/linter --audit-only
npx @enigmax/linter --style-only

# apply safe formatting fixes in place, then report what remains
npx @enigmax/linter --fix

# machine-readable output
npx @enigmax/linter --json

# fail on warnings too (e.g. a changed-files commit/CI gate)
npx @enigmax/linter --strict

By default the CLI exits non-zero only on error-severity findings (URL/CDN imports, hardcoded secrets). --strict also fails on warning-severity Ciphera style findings, which is what a pre-commit or CI gate over changed files wants.

--fix rewrites only the mechanical rules, the ones whose fix cannot change what the program does: trailing whitespace, blank lines (collapsed, with leading/trailing removed), the final newline, the order of a contiguous import group, the semicolon terminating an interface or type-literal member, and the trailing comma in a named import/export list. The judgement-dependent style rules (quotes, statement semicolons, concatenation) and the security audits are reported, never rewritten. Container formats (.ipynb, .astro, .vue, .svelte) are left untouched by --fix.

The two punctuation fixes stand down when the file sits in a project configured with Prettier (a .prettierrc* / prettier.config.* file, or a prettier key in a package.json, anywhere from the file's directory up to the project root - the first directory holding .git, so a stray config in a home directory decides nothing). Prettier strips a single-line type literal's terminator and defaults to trailingComma: "all", so rewriting there would only make the two formatters flip the same lines back and forth. The two rules that report it (require-semicolons over type members, no-import-trailing-comma) go silent there as well, rather than block on a finding the fixer refuses to fix. Every other fix and every other rule keeps running, including require-semicolons over statements.

The bin is enigmax-lint. It exits non-zero when any error-severity violation is found (URL/CDN imports, hardcoded secrets), so it can gate a commit or CI step.

Rules

Style (Ciphera)

Audit (security)

To keep false positives low, a match is only reported when its random portion looks like a real credential: obvious placeholders (your_api_key_here, changeme, ...) and low-entropy fillers (sk-proj-000000000000, repeated characters) are ignored. Files named *example*, *sample*, *template*, *fixture*, *.test.*, and *.spec.* are exempt from the secret audit entirely.

Programmatic API

import { lintFiles, lintText } from "@enigmax/linter";

const violations = lintFiles(["src"], { categories: ["audit"] });
const inline = lintText("snippet.ts", "const x = 'a'");

Style scope

These rules encode the Ciphera conventions for new code. Per the policy, existing files should match their established style; do not reformat working code just to satisfy the linter.