lanekeep 0.1.0

package/README.md

@@ -0,0 +1,249 @@
+# lanekeep
+
+**Deterministic, AST-based architectural conformance checking for AI-generated and human-written code.**
+
+[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](#license)
+
+> **Status: early development.** Nothing is released yet and the CLI described below is not
+> usable. The architecture is settled — see [`docs/architecture.md`](docs/architecture.md) — and
+> the work is tracked as a sequence of milestones. Do not depend on this yet.
+
+---
+
+## What it is
+
+lanekeep is not a linter in the ESLint sense. ESLint enforces language-level correctness.
+lanekeep enforces *project-specific conventions* — the ones a language model has no way to infer
+from the code it is shown, because they live in your team's heads and your reviewers' comments.
+
+Every rule is a codified answer to **"the agent keeps doing this wrong."**
+
+Rules are TypeScript programs, written in the same language as the code they inspect:
+
+```ts
+import { defineRule } from 'lanekeep'
+
+export default defineRule({
+  id: 'local/no-numeric-sizes',
+  severity: 'error',
+
+  card: {
+    message: 'Literal numeric size inside makeStyles',
+    remediation: 'Use theme.spacing.*, theme.borderRadius.* or theme.borders.*',
+    examples: { bad: 'padding: 12', good: 'padding: theme.spacing.md' },
+  },
+
+  // Matched in Rust, at native speed. Your code runs only on matches.
+  query: `
+    (pair
+      key: (property_identifier) @prop
+      value: [(number) (unary_expression operand: (number))] @value) @match
+  `,
+
+  check(ctx, m) {
+    if (!/^(padding|margin|gap|borderRadius)/.test(ctx.text(m.prop))) return
+    if (Number(ctx.text(m.value)) === 0) return
+
+    const call = ctx.closestAncestor(m.match, '(call_expression function: (identifier) @f)')
+    if (!call) return
+    if (!ctx.resolvesToImport(call.f, { module: '@rneui/themed', name: 'makeStyles' })) return
+
+    ctx.report(m.match)
+  },
+})
+```
+
+`check` is ordinary TypeScript. Loop, accumulate state, build data structures, read other files,
+import shared helpers — there is no expressiveness ceiling and no DSL to learn beyond the query
+that gates it.
+
+## Why it exists
+
+An agent that writes code against your codebase will violate your conventions confidently and
+repeatedly, because those conventions are invisible in the code it was shown. Telling it again in
+the next prompt does not scale. Encoding the convention as a rule does.
+
+That makes the design constraints unusual for a static analyzer:
+
+- **It runs in the inner loop.** Agents and developers invoke it after every edit, so a cold run
+  on a couple of thousand files has a sub-second budget and a warm run has a sub-25ms one.
+- **Its output is read by a machine.** Violations are sorted deterministically, because an agent
+  that reads the output twice must not see reordering as change.
+- **Every rule carries its own fix.** `message`, `remediation` and `examples` are mandatory
+  fields, not documentation — they are the rule card that gets fed back to the agent.
+
+## How it stays fast with programmable rules
+
+The usual problem with a native tool that runs JavaScript plugins is the boundary between them:
+dispatching into JS once per AST node means tens of thousands of crossings per file.
+
+lanekeep dispatches once per **query match** instead. The tree-sitter query runs in Rust across a
+single shared parse; only matches reach your handler. That is typically two to three orders of
+magnitude fewer crossings, and it is the reason a Rust engine still earns its place once rules are
+TypeScript.
+
+```
+discover paths (globs, gitignore-aware)
+  └─> for each file, in parallel:
+        cache key ──hit──> validate tracked deps ──> cached violations + facts
+                  └─miss─> path and raw-text gates reject before any parse
+                           └─> parse ─> match queries in Rust
+                               └─> invoke the TypeScript handler, per match only
+  └─> reduce phase: cross-file rules consume facts only, never parse trees
+  └─> filter suppressions ─> sort ─> report
+```
+
+A warm run with no changes executes no JavaScript at all — every file is a cache hit.
+
+## Installation
+
+Not yet published. The distribution is built and tested — one npm package per platform plus a
+launcher that resolves the right one, and every crate publishable to crates.io — but no
+version has been released yet.
+
+When it ships:
+
+```bash
+npm install --save-dev lanekeep    # or: cargo install lanekeep-cli
+```
+
+A single static binary with the JavaScript engine compiled in. **Node.js is not required to
+run lanekeep**, even though rules are written in TypeScript — it is required only to install
+it from npm, where it picks which binary to fetch.
+
+Prebuilt for macOS on Apple silicon, Linux on x86-64 and arm64, and Windows on x86-64.
+Intel macOS is not prebuilt — `cargo install lanekeep-cli` builds it from source, and the
+npm launcher says so rather than failing obscurely.
+
+See [`docs/releasing.md`](docs/releasing.md) for how a release is cut.
+
+## What it looks like
+
+```
+$ lanekeep check
+src/also.ts:2:1 error [lanekeep/no-default-export] default export
+  → use a named export, so the symbol has one name every importer must use
+src/bad.ts:2:1 error [lanekeep/no-default-export] default export
+  → use a named export, so the symbol has one name every importer must use
+
+✖ 2 error(s) across 2 file(s) checked
+```
+
+Rules may offer a fix, applied with `--fix`:
+
+```
+$ lanekeep check --fix
+fixed 2 violation(s) in 2 file(s)
+```
+
+Only fixes a rule marked as behavior-preserving are applied. Anything else is a suggestion —
+shown, never written — because the cautious mistake costs a manual edit and the other one
+rewrites your code silently.
+
+Suppressions carry a mandatory reason and an optional expiry, and a directive that does not
+work says so — a missing reason, a bare rule id, or an unreadable date is reported rather
+than silently doing nothing:
+
+```ts
+// lanekeep-ignore-next-line lanekeep/no-default-export reason: legacy entry point
+export default parse
+```
+
+```
+$ lanekeep check --report-unused-suppressions
+```
+
+To start from nothing:
+
+```
+$ lanekeep init          # a config plus a first rule, both runnable
+```
+
+To find out where a run spent its time — the split says whether the query or the code is
+the problem:
+
+```
+$ lanekeep check --profile
+```
+
+To find out what a rule wants without opening its source:
+
+```
+$ lanekeep explain lanekeep/no-default-export
+$ lanekeep rules --json
+```
+
+For fast feedback on what you touched:
+
+```
+$ lanekeep check --staged     # what is about to be committed
+$ lanekeep check --since main # what changed against a ref
+```
+
+Both are intersected with the config's `include`/`exclude`, and both skip cross-file rules —
+a whole-corpus rule over a subset gives a wrong answer, not a smaller one, so they are
+skipped and named on stderr rather than quietly producing one.
+
+Exit `0` when clean, `1` when violations are found, `2` when the checker could not run —
+a caller has to be able to tell "your code has problems" from "the tool is broken".
+Four output formats: `human` (default), `json` (versioned, stable schema), `sarif` (GitHub
+code scanning), and `agent` — token-minimal, grouped by rule rather than by file, with each
+rule's card stated once instead of once per violation. Diagnostics always go to stderr, so
+piping into a parser works even when something fails.
+
+## Documentation
+
+| Document | Purpose |
+| --- | --- |
+| [`docs/architecture.md`](docs/architecture.md) | The full design: execution model, host API, cache, milestones |
+| [`docs/built-in-rules.md`](docs/built-in-rules.md) | The rules lanekeep ships with, and their options |
+| [`docs/cross-file-rules.md`](docs/cross-file-rules.md) | Writing a rule that needs a whole-corpus view |
+| [`AGENTS.md`](AGENTS.md) | How to work in this repository — for coding agents and humans alike |
+| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Setup, commands, and the pull request process |
+| [`SECURITY.md`](SECURITY.md) | Threat model and how to report a vulnerability |
+| [`docs/releasing.md`](docs/releasing.md) | How a release is built, gated and published |
+
+## Security
+
+lanekeep is meant to run as a pre-commit hook and inside CI, which makes it a supply-chain target.
+Rules are executable code, so the posture is about confinement rather than absence:
+
+- **No ambient authority.** Rules run in an embedded QuickJS sandbox and reach exactly the host
+  functions lanekeep exposes. `fs`, `process`, `child_process`, network and dynamic import are not
+  restricted — they do not exist in the context.
+- **No network access.** Ever, in any mode, with no configuration that enables it.
+- **Filesystem confinement.** Reads go through a tracked `ctx.readFile`, confined to the project
+  root. Writes happen only under `--fix`, only to matched files, only within reported ranges.
+- **Bounded execution.** A per-invocation timeout, a 15-second global run budget and a per-runtime
+  memory ceiling, none disableable — a rule that hangs a pre-commit hook is indistinguishable from
+  a broken tool. Breaching any of them cancels the run and exits `2`, rather than reporting a
+  partial result as a clean one.
+- **Deterministic by construction.** The sandbox withholds the clock and randomness, so a rule
+  cannot introduce nondeterminism even by accident.
+
+This bounds blast radius and makes third-party rule sets reviewable. It is not a boundary against
+someone who can already commit to the repository being checked. To report a vulnerability, see
+[`SECURITY.md`](SECURITY.md).
+
+## Contributing
+
+Contributions are welcome, particularly new built-in rules and new host API surface. Start
+with [`CONTRIBUTING.md`](CONTRIBUTING.md) — `./scripts/setup-dev.sh` installs everything and
+wires the git hooks.
+
+All work ships as squashed pull requests with [Conventional Commits](https://www.conventionalcommits.org/)
+titles. `main` is protected and takes no direct pushes.
+
+## License
+
+Licensed under either of
+
+- Apache License, Version 2.0 ([`LICENSE-APACHE`](LICENSE-APACHE) or
+  <http://www.apache.org/licenses/LICENSE-2.0>)
+- MIT License ([`LICENSE-MIT`](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
+
+at your option.
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in
+this work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without
+any additional terms or conditions.

package/bin/lanekeep

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * Hand control to the platform binary.
+ *
+ * lanekeep's exit code is load-bearing — 0 clean, 1 violations, 2 could not run — so this
+ * wrapper's whole job is to pass it through unchanged, along with stdio and any signal that
+ * killed the child.
+ *
+ * A `spawnSync` with inherited stdio rather than an `execve`: replacing the process would be
+ * marginally cleaner on Unix, Node has no way to do it without a native dependency, and a
+ * native dependency in the package whose entire point is not needing one is the wrong trade.
+ * The cost is one idle Node process for the duration of a run.
+ */
+
+const { spawnSync } = require('node:child_process')
+
+const { resolveBinary } = require('../resolve.js')
+
+let binary
+try {
+  binary = resolveBinary()
+} catch (error) {
+  process.stderr.write(`${error.message}\n`)
+  // 2, not 1: lanekeep could not run, which is not the same as finding violations. A
+  // pre-commit hook that read a broken install as "your code has problems" would be worse
+  // than useless — it would block on something the author cannot fix by editing code.
+  process.exit(2)
+}
+
+const result = spawnSync(binary, process.argv.slice(2), {
+  stdio: 'inherit',
+  windowsHide: true,
+})
+
+if (result.error) {
+  process.stderr.write(`lanekeep could not start: ${result.error.message}\n`)
+  process.exit(2)
+}
+
+if (result.signal) {
+  // Re-raised rather than turned into an exit code, so a caller that distinguishes a killed
+  // process from a failing one still can. Windows reports none, so this never fires there.
+  process.kill(process.pid, result.signal)
+}
+
+// `null` means the child died from a signal the platform did not name. The run did not
+// finish, so 2 is the honest answer.
+process.exit(result.status ?? 2)

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "lanekeep",
+  "version": "0.1.0",
+  "description": "Deterministic, AST-based architectural conformance checking",
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fmsouza/lanekeep.git"
+  },
+  "homepage": "https://github.com/fmsouza/lanekeep#readme",
+  "bin": {
+    "lanekeep": "bin/lanekeep"
+  },
+  "files": [
+    "bin/lanekeep",
+    "resolve.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "@lanekeep/darwin-arm64": "0.1.0",
+    "@lanekeep/linux-arm64": "0.1.0",
+    "@lanekeep/linux-x64": "0.1.0",
+    "@lanekeep/win32-x64": "0.1.0"
+  }
+}

package/resolve.js

@@ -0,0 +1,72 @@
+/**
+ * Find the platform binary this machine should run.
+ *
+ * lanekeep ships one npm package per platform and a launcher — this one — that depends on
+ * all of them as `optionalDependencies`. npm installs only the one whose `os` and `cpu` match,
+ * so a developer downloads one binary rather than five.
+ *
+ * **Node is not required to run lanekeep.** It is required only to install it this way. The
+ * binary has the JavaScript engine compiled in; this file exists to pick which binary.
+ */
+
+const { existsSync } = require('node:fs')
+
+/**
+ * The platform packages, keyed by what Node reports.
+ *
+ * Written out rather than composed from `${platform}-${arch}`, so a platform lanekeep does
+ * not publish for produces a message naming what is available instead of a confusing
+ * "cannot find module @lanekeep/sunos-sparc".
+ */
+const PACKAGES = {
+  'darwin-arm64': '@lanekeep/darwin-arm64',
+  'linux-arm64': '@lanekeep/linux-arm64',
+  'linux-x64': '@lanekeep/linux-x64',
+  'win32-x64': '@lanekeep/win32-x64',
+}
+
+/** Where the binary sits inside a platform package. */
+function binaryName(platform) {
+  return platform === 'win32' ? 'lanekeep.exe' : 'lanekeep'
+}
+
+/**
+ * The path to this machine's lanekeep binary.
+ *
+ * @throws if this platform has no package, or the package is missing.
+ */
+function resolveBinary(platform = process.platform, arch = process.arch) {
+  const key = `${platform}-${arch}`
+  const pkg = PACKAGES[key]
+
+  if (!pkg) {
+    throw new Error(
+      `lanekeep does not ship a binary for ${key}\n` +
+        `  available: ${Object.keys(PACKAGES).sort().join(', ')}\n` +
+        `  build from source with: cargo install lanekeep-cli`,
+    )
+  }
+
+  let binary
+  try {
+    // Resolved through Node rather than joined by hand, so it works with npm, pnpm's
+    // symlinked store, and Yarn's zero-install layout — three arrangements that agree on
+    // `require.resolve` and on nothing else.
+    binary = require.resolve(`${pkg}/bin/${binaryName(platform)}`)
+  } catch {
+    throw new Error(
+      `lanekeep's binary for ${key} is not installed\n` +
+        `  expected the optional dependency ${pkg}\n` +
+        `  this usually means the install ran with --no-optional, or on a different platform\n` +
+        `  reinstall with: npm install lanekeep`,
+    )
+  }
+
+  if (!existsSync(binary)) {
+    throw new Error(`lanekeep's binary for ${key} is missing at ${binary}`)
+  }
+
+  return binary
+}
+
+module.exports = { PACKAGES, binaryName, resolveBinary }