@nifrajs/cli 3.1.0 → 3.3.0

package/src/rules/islands.ts

@@ -0,0 +1,171 @@
+import type * as TSApi from "typescript"
+import { type Diagnostic, diagnostic } from "../diagnostics.ts"
+import { importProjectTypeScript } from "../internal/typescript-import.ts"
+import type { CheckRule, SourceIndex } from "./index.ts"
+
+/**
+ * NF-C020 - the island cleanup lint. An island enhancer (`@nifrajs/web/islands`) runs once and must
+ * hand back a teardown for anything it wires: `mountIslands`'s disposer calls it on soft-nav, and
+ * without it every navigation leaks the listener. This is the single mistake an agent writing
+ * imperative island code makes most - it adds `el.addEventListener(...)` and forgets the `return`.
+ * The lint watches the two authoring shapes and warns (never blocks) when a block-body enhancer adds
+ * a listener but returns no cleanup:
+ *
+ *   defineIsland((el) => { el.addEventListener("click", f) })          // ← flagged: no cleanup
+ *   defineIsland((el) => { el.addEventListener("click", f); return () => el.removeEventListener("click", f) })  // ok
+ *   mountIslands({ x: (el) => { el.addEventListener("click", f) } })   // ← flagged
+ *
+ * Deliberately conservative to stay false-positive-free: a concise-body arrow (`(el) => bus.on(...)`)
+ * already IS a returned value, so it is never flagged; a block that returns anything is trusted as
+ * cleanup; only an inline function literal is inspected (a `defineIsland(...)` result referenced by
+ * name is caught at its definition site, never twice).
+ */
+
+const parseCache = new WeakMap<
+  SourceIndex,
+  Map<string, { readonly tree: TSApi.SourceFile } | null>
+>()
+
+function parsedTree(
+  ts: typeof TSApi,
+  sources: SourceIndex,
+  file: string,
+): TSApi.SourceFile | undefined {
+  let files = parseCache.get(sources)
+  if (files === undefined) {
+    files = new Map()
+    parseCache.set(sources, files)
+  }
+  const cached = files.get(file)
+  if (cached !== undefined) return cached?.tree
+  const source = sources.read(file)
+  if (source === undefined) {
+    files.set(file, null)
+    return undefined
+  }
+  const kind = /\.tsx?$/.test(file) ? ts.ScriptKind.TSX : ts.ScriptKind.JS
+  const tree = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, kind)
+  files.set(file, { tree })
+  return tree
+}
+
+type EnhancerFn = TSApi.ArrowFunction | TSApi.FunctionExpression
+
+function isEnhancerFn(ts: typeof TSApi, node: TSApi.Node): node is EnhancerFn {
+  return ts.isArrowFunction(node) || ts.isFunctionExpression(node)
+}
+
+/** Any `<expr>.addEventListener(...)` reachable inside the enhancer (nested handlers included - the
+ * presence of the wiring is what matters, not its depth). */
+function addsListener(ts: typeof TSApi, fn: EnhancerFn): boolean {
+  let found = false
+  const walk = (node: TSApi.Node): void => {
+    if (found) return
+    if (
+      ts.isCallExpression(node) &&
+      ts.isPropertyAccessExpression(node.expression) &&
+      node.expression.name.text === "addEventListener"
+    ) {
+      found = true
+      return
+    }
+    ts.forEachChild(node, walk)
+  }
+  ts.forEachChild(fn, walk)
+  return found
+}
+
+/** Does the enhancer hand back a value? A concise-body arrow always does. A block body counts only a
+ * `return <expr>` that is NOT inside a nested function (a nested handler's return is not the
+ * enhancer's cleanup). */
+function returnsCleanup(ts: typeof TSApi, fn: EnhancerFn): boolean {
+  if (ts.isArrowFunction(fn) && !ts.isBlock(fn.body)) return true // concise body IS the return value
+  let found = false
+  const walk = (node: TSApi.Node): void => {
+    if (found) return
+    if (isEnhancerFn(ts, node) || ts.isFunctionDeclaration(node)) return // don't descend into nested fns
+    if (ts.isReturnStatement(node) && node.expression !== undefined) {
+      found = true
+      return
+    }
+    ts.forEachChild(node, walk)
+  }
+  ts.forEachChild(fn, walk)
+  return found
+}
+
+/** The inline enhancer functions authored in `file`: the argument to `defineIsland(...)` and every
+ * function-typed value of a `mountIslands({ ... })` object literal. */
+function enhancerFns(ts: typeof TSApi, tree: TSApi.SourceFile): EnhancerFn[] {
+  const out: EnhancerFn[] = []
+  const visit = (node: TSApi.Node): void => {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+      const callee = node.expression.text
+      if (callee === "defineIsland") {
+        const arg = node.arguments[0]
+        if (arg !== undefined && isEnhancerFn(ts, arg)) out.push(arg)
+      } else if (callee === "mountIslands") {
+        const arg = node.arguments[0]
+        if (arg !== undefined && ts.isObjectLiteralExpression(arg)) {
+          for (const prop of arg.properties) {
+            // Only inline function literals `{ x: (el) => {…} }` are inspected. A shorthand method
+            // `{ x(el) {…} }` or a named reference `{ x: counter }` is left to its definition site.
+            if (ts.isPropertyAssignment(prop) && isEnhancerFn(ts, prop.initializer))
+              out.push(prop.initializer)
+          }
+        }
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(tree)
+  return out
+}
+
+export const islandCleanupRule: CheckRule = {
+  code: "NF-C020",
+  title: "Island enhancer cleanup check",
+  async scan(ctx) {
+    const ts = await importProjectTypeScript(ctx.root)
+    if (ts === undefined) {
+      return [
+        diagnostic({
+          code: "NF-C020",
+          severity: "warn",
+          message:
+            "Island enhancer cleanup check (NF-C020) did NOT run - TypeScript is not installed, so this report says nothing about it",
+          fix: { recipe: "toolchain.install-typescript", command: "bun add -d typescript" },
+          verify: "nifra check --lints-only",
+        }),
+      ]
+    }
+    const findings: Diagnostic[] = []
+    for (const file of ctx.project.source.files) {
+      const tree = parsedTree(ts, ctx.project.source, file)
+      if (tree === undefined) continue
+      for (const fn of enhancerFns(ts, tree)) {
+        if (!addsListener(ts, fn) || returnsCleanup(ts, fn)) continue
+        const line = tree.getLineAndCharacterOfPosition(fn.getStart(tree)).line + 1
+        findings.push(
+          diagnostic({
+            code: "NF-C020",
+            severity: "warn",
+            file,
+            line,
+            message:
+              "island enhancer adds an event listener but returns no cleanup - it leaks on soft-nav teardown",
+            evidence: ["addEventListener without a returned cleanup"],
+            fix: {
+              recipe: "islands.return-cleanup",
+              command: "nifra_docs islands",
+            },
+            verify: "nifra check --lints-only",
+          }),
+        )
+      }
+    }
+    return findings
+  },
+}
+
+export const islandRules = Object.freeze([islandCleanupRule])

package/src/rules/nano.ts

@@ -0,0 +1,295 @@
+import type * as TSApi from "typescript"
+import { type Diagnostic, diagnostic } from "../diagnostics.ts"
+import { importProjectTypeScript } from "../internal/typescript-import.ts"
+import type { CheckRule, SourceIndex } from "./index.ts"
+
+/**
+ * The nano lane lints (`@nifrajs/web/nano`). nano is deliberately explicit - every reactive edge is a
+ * `bind`/`bindList` call or a `computed(fn, [deps])` - and that is exactly what makes its three
+ * mistakes STATICALLY catchable, the property a framework's auto-tracked reactivity cannot offer:
+ *
+ *   NF-C021  a `bind`/`bindList`/`bindResource` whose disposer is discarded (leaks on teardown)
+ *   NF-C022  a `bindList` keyed by the array index (breaks add/remove/reorder)
+ *   NF-C023  a `computed`/`resource` `(fn, [deps])` reading a signal its `deps` omit (won't recompute/refetch)
+ *
+ * All three warn (never block): a false positive must never fail a build, and each maps to a fix
+ * recipe (`nano.*`). Deliberately conservative - only the unambiguous authoring shapes are inspected.
+ */
+
+const parseCache = new WeakMap<
+  SourceIndex,
+  Map<string, { readonly tree: TSApi.SourceFile } | null>
+>()
+
+function parsedTree(
+  ts: typeof TSApi,
+  sources: SourceIndex,
+  file: string,
+): TSApi.SourceFile | undefined {
+  let files = parseCache.get(sources)
+  if (files === undefined) {
+    files = new Map()
+    parseCache.set(sources, files)
+  }
+  const cached = files.get(file)
+  if (cached !== undefined) return cached?.tree
+  const source = sources.read(file)
+  if (source === undefined) {
+    files.set(file, null)
+    return undefined
+  }
+  const kind = /\.tsx?$/.test(file) ? ts.ScriptKind.TSX : ts.ScriptKind.JS
+  const tree = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, kind)
+  files.set(file, { tree })
+  return tree
+}
+
+type Fn = TSApi.ArrowFunction | TSApi.FunctionExpression
+const isFn = (ts: typeof TSApi, n: TSApi.Node): n is Fn =>
+  ts.isArrowFunction(n) || ts.isFunctionExpression(n)
+
+/** Names bound to a `signal(...)` or `computed(...)` result anywhere in the file - the reactive cells
+ * a `computed` body may read and must therefore declare. */
+function reactiveBindings(ts: typeof TSApi, tree: TSApi.SourceFile): Set<string> {
+  const names = new Set<string>()
+  const visit = (n: TSApi.Node): void => {
+    if (
+      ts.isVariableDeclaration(n) &&
+      ts.isIdentifier(n.name) &&
+      n.initializer !== undefined &&
+      ts.isCallExpression(n.initializer) &&
+      ts.isIdentifier(n.initializer.expression) &&
+      (n.initializer.expression.text === "signal" ||
+        n.initializer.expression.text === "computed" ||
+        n.initializer.expression.text === "resource")
+    ) {
+      names.add(n.name.text)
+    }
+    ts.forEachChild(n, visit)
+  }
+  visit(tree)
+  return names
+}
+
+/** Reactive identifiers read as `x.get()` inside `fn`. */
+function getsInside(ts: typeof TSApi, fn: TSApi.Node, reactive: ReadonlySet<string>): Set<string> {
+  const reads = new Set<string>()
+  const visit = (n: TSApi.Node): void => {
+    if (
+      ts.isCallExpression(n) &&
+      ts.isPropertyAccessExpression(n.expression) &&
+      n.expression.name.text === "get" &&
+      ts.isIdentifier(n.expression.expression) &&
+      reactive.has(n.expression.expression.text)
+    ) {
+      reads.add(n.expression.expression.text)
+    }
+    ts.forEachChild(n, visit)
+  }
+  visit(fn)
+  return reads
+}
+
+/** The identifiers listed in a `computed`'s deps array literal (non-identifier entries are ignored -
+ * an unusual deps shape simply isn't linted rather than mis-flagged). */
+function declaredDeps(ts: typeof TSApi, depsArg: TSApi.Expression): Set<string> {
+  const deps = new Set<string>()
+  if (ts.isArrayLiteralExpression(depsArg)) {
+    for (const el of depsArg.elements) if (ts.isIdentifier(el)) deps.add(el.text)
+  }
+  return deps
+}
+
+/** A `bind`/`bindList` call whose return value is discarded: its immediate parent is the expression
+ * statement itself (not an assignment, array element, `return`, `await`, or argument). */
+function isDiscarded(ts: typeof TSApi, call: TSApi.CallExpression): boolean {
+  const parent = call.parent
+  return parent !== undefined && ts.isExpressionStatement(parent)
+}
+
+/** For a `bindList(src, container, { key, ... })`, the `key` property's function if it is an inline
+ * arrow/function literal. */
+function keyFn(ts: typeof TSApi, call: TSApi.CallExpression): Fn | undefined {
+  const opts = call.arguments[2]
+  if (opts === undefined || !ts.isObjectLiteralExpression(opts)) return undefined
+  for (const prop of opts.properties) {
+    if (
+      ts.isPropertyAssignment(prop) &&
+      ts.isIdentifier(prop.name) &&
+      prop.name.text === "key" &&
+      isFn(ts, prop.initializer)
+    ) {
+      return prop.initializer
+    }
+  }
+  return undefined
+}
+
+/** Does `fn`'s body return its own second parameter (the index) directly? `key: (_, i) => i`, the
+ * classic reorder-breaking key. Conservative: only a bare `return <secondParam>` / concise `=> i`. */
+function returnsSecondParam(ts: typeof TSApi, fn: Fn): boolean {
+  if (fn.parameters.length < 2) return false
+  const second = fn.parameters[1]
+  if (second === undefined || !ts.isIdentifier(second.name)) return false
+  const idx = second.name.text
+  const isIdxRef = (e: TSApi.Expression): boolean => ts.isIdentifier(e) && e.text === idx
+  if (ts.isArrowFunction(fn) && !ts.isBlock(fn.body)) return isIdxRef(fn.body)
+  let found = false
+  const visit = (n: TSApi.Node): void => {
+    if (found) return
+    if (isFn(ts, n) || ts.isFunctionDeclaration(n)) return // not a nested fn's return
+    if (ts.isReturnStatement(n) && n.expression !== undefined && isIdxRef(n.expression)) {
+      found = true
+      return
+    }
+    ts.forEachChild(n, visit)
+  }
+  ts.forEachChild(fn, visit)
+  return found
+}
+
+const lineOf = (tree: TSApi.SourceFile, n: TSApi.Node): number =>
+  tree.getLineAndCharacterOfPosition(n.getStart(tree)).line + 1
+
+function toolchainMissing(code: string): Diagnostic {
+  return diagnostic({
+    code,
+    severity: "warn",
+    message: `nano lint (${code}) did NOT run - TypeScript is not installed, so this report says nothing about it`,
+    fix: { recipe: "toolchain.install-typescript", command: "bun add -d typescript" },
+    verify: "nifra check --lints-only",
+  })
+}
+
+export const nanoBindCleanupRule: CheckRule = {
+  code: "NF-C021",
+  title: "nano binding cleanup check",
+  async scan(ctx) {
+    const ts = await importProjectTypeScript(ctx.root)
+    if (ts === undefined) return [toolchainMissing("NF-C021")]
+    const findings: Diagnostic[] = []
+    for (const file of ctx.project.source.files) {
+      const tree = parsedTree(ts, ctx.project.source, file)
+      if (tree === undefined) continue
+      const visit = (n: TSApi.Node): void => {
+        if (
+          ts.isCallExpression(n) &&
+          ts.isIdentifier(n.expression) &&
+          (n.expression.text === "bind" ||
+            n.expression.text === "bindList" ||
+            n.expression.text === "bindResource") &&
+          isDiscarded(ts, n)
+        ) {
+          findings.push(
+            diagnostic({
+              code: "NF-C021",
+              severity: "warn",
+              file,
+              line: lineOf(tree, n),
+              message: `${n.expression.text}(...) discards its cleanup - collect the returned disposer and call it on teardown, or it leaks on soft-nav`,
+              evidence: [`${n.expression.text}(...) as a bare statement`],
+              fix: { recipe: "nano.collect-cleanup", command: "nifra_docs nano" },
+              verify: "nifra check --lints-only",
+            }),
+          )
+        }
+        ts.forEachChild(n, visit)
+      }
+      visit(tree)
+    }
+    return findings
+  },
+}
+
+export const nanoListKeyRule: CheckRule = {
+  code: "NF-C022",
+  title: "nano bindList key check",
+  async scan(ctx) {
+    const ts = await importProjectTypeScript(ctx.root)
+    if (ts === undefined) return [toolchainMissing("NF-C022")]
+    const findings: Diagnostic[] = []
+    for (const file of ctx.project.source.files) {
+      const tree = parsedTree(ts, ctx.project.source, file)
+      if (tree === undefined) continue
+      const visit = (n: TSApi.Node): void => {
+        if (
+          ts.isCallExpression(n) &&
+          ts.isIdentifier(n.expression) &&
+          n.expression.text === "bindList"
+        ) {
+          const key = keyFn(ts, n)
+          if (key !== undefined && returnsSecondParam(ts, key)) {
+            findings.push(
+              diagnostic({
+                code: "NF-C022",
+                severity: "warn",
+                file,
+                line: lineOf(tree, key),
+                message:
+                  "bindList key is the array index - add/remove/reorder will reuse the wrong node. Key by a stable id on the item instead",
+                evidence: ["key: (_, i) => i"],
+                fix: { recipe: "nano.stable-key", command: "nifra_docs nano" },
+                verify: "nifra check --lints-only",
+              }),
+            )
+          }
+        }
+        ts.forEachChild(n, visit)
+      }
+      visit(tree)
+    }
+    return findings
+  },
+}
+
+export const nanoComputedDepsRule: CheckRule = {
+  code: "NF-C023",
+  title: "nano computed deps check",
+  async scan(ctx) {
+    const ts = await importProjectTypeScript(ctx.root)
+    if (ts === undefined) return [toolchainMissing("NF-C023")]
+    const findings: Diagnostic[] = []
+    for (const file of ctx.project.source.files) {
+      const tree = parsedTree(ts, ctx.project.source, file)
+      if (tree === undefined) continue
+      const reactive = reactiveBindings(ts, tree)
+      if (reactive.size === 0) continue
+      const visit = (n: TSApi.Node): void => {
+        const fnArg = ts.isCallExpression(n) ? n.arguments[0] : undefined
+        const depsArg = ts.isCallExpression(n) ? n.arguments[1] : undefined
+        const callName =
+          ts.isCallExpression(n) && ts.isIdentifier(n.expression) ? n.expression.text : undefined
+        if (
+          (callName === "computed" || callName === "resource") &&
+          fnArg !== undefined &&
+          depsArg !== undefined &&
+          isFn(ts, fnArg)
+        ) {
+          const reads = getsInside(ts, fnArg, reactive)
+          const deps = declaredDeps(ts, depsArg)
+          const missing = [...reads].filter((r) => !deps.has(r))
+          if (missing.length > 0) {
+            const verb = callName === "resource" ? "refetch" : "recompute"
+            findings.push(
+              diagnostic({
+                code: "NF-C023",
+                severity: "warn",
+                file,
+                line: lineOf(tree, n),
+                message: `${callName} reads ${JSON.stringify([...reads])} but its deps declare ${JSON.stringify([...deps])} - it will not ${verb} when ${missing.join(", ")} changes. Add ${missing.join(", ")} to the deps array`,
+                evidence: [`missing dep: ${missing.join(", ")}`],
+                fix: { recipe: "nano.declare-deps", command: "nifra_docs nano" },
+                verify: "nifra check --lints-only",
+              }),
+            )
+          }
+        }
+        ts.forEachChild(n, visit)
+      }
+      visit(tree)
+    }
+    return findings
+  },
+}
+
+export const nanoRules = Object.freeze([nanoBindCleanupRule, nanoListKeyRule, nanoComputedDepsRule])

package/src/rules/security.ts

@@ -61,9 +61,29 @@ function nameOf(ts: typeof TSApi, node: TSApi.Node): string | undefined {
   return undefined
 }
 
+/**
+ * The operand name to match secret-like patterns against for NF-S002, or undefined when the operand
+ * cannot hold runtime secret material. A property access to an uppercase-initial member
+ * (`ts.SyntaxKind.PlusToken`, `MediaKind.Audio`) reads an enum/type-constant discriminant, never a
+ * secret string or byte buffer, so comparing against it is a kind check a timing oracle does not
+ * apply to. Runtime secret fields follow the camelCase convention (`apiToken`, `signature`), so an
+ * uppercase-initial member is a safe exclusion. Identifiers stay matched in every case, so an
+ * `UPPER_SNAKE` secret constant still surfaces.
+ */
+function secretName(ts: typeof TSApi, node: TSApi.Node): string | undefined {
+  if (ts.isPropertyAccessExpression(node)) {
+    const member = node.name.text
+    return /^[A-Z]/.test(member) ? undefined : member
+  }
+  return nameOf(ts, node)
+}
+
 /**
  * Presence checks (`token === undefined`, `secret == null`, `apiKey !== ""`) and `typeof` guards are
  * not equality over secret material - rewriting them to a timing-safe comparison would break the code.
+ * A comparison against a numeric literal (`signature !== 1`, `signatureLength !== 64`) is a
+ * length/version/discriminant check, never a secret: secrets are strings or bytes, so a number on
+ * either side proves this is not the compare a timing oracle applies to.
  */
 function isPresenceComparison(ts: typeof TSApi, node: TSApi.BinaryExpression): boolean {
   for (const side of [node.left, node.right]) {
@@ -72,6 +92,8 @@ function isPresenceComparison(ts: typeof TSApi, node: TSApi.BinaryExpression): b
     if (ts.isStringLiteralLike(side) && side.text === "") return true
     if (ts.isTypeOfExpression(side)) return true
     if (ts.isVoidExpression(side)) return true
+    if (ts.isNumericLiteral(side)) return true
+    if (ts.isPrefixUnaryExpression(side) && ts.isNumericLiteral(side.operand)) return true
   }
   return false
 }
@@ -123,8 +145,8 @@ export const secretComparisonRule: CheckRule = {
           ].includes(node.operatorToken.kind) &&
           !isPresenceComparison(ts, node)
         ) {
-          const left = nameOf(ts, node.left)
-          const right = nameOf(ts, node.right)
+          const left = secretName(ts, node.left)
+          const right = secretName(ts, node.right)
           if (
             (left !== undefined && SECRET.test(left)) ||
             (right !== undefined && SECRET.test(right))
@@ -229,9 +251,23 @@ export const failOpenGateRule: CheckRule = {
             ts.isFunctionLike(parent) && parent.name && ts.isIdentifier(parent.name)
               ? parent.name.text
               : undefined
-          if (name !== undefined && /^(?:require|assert|can|authorize)/i.test(name)) {
+          // `can` only names a gate in camelCase (`canEdit`, `canAccess`) - matching it
+          // case-insensitively swept in `canonicalize…`, `cancel…`, `candidate…`, none of them
+          // authorization decisions. The other roots stay case-insensitive.
+          const gateName =
+            name !== undefined &&
+            (/^(?:require|assert|authorize)/i.test(name) || /^can[A-Z]/.test(name))
+          if (name !== undefined && gateName) {
             const text = node.block.getText(tree)
-            if (!/\b(?:throw|return\s+(?:false|new\s+Response|deny))/s.test(text)) {
+            // A catch fails closed when it rethrows, returns an explicit denial, or hands the failure
+            // to a helper whose whole job is to fail (`fail(…)`, `deny(…)`, `reject(…)`, …). The last
+            // form is why conformance/invariant asserts that funnel every error through a
+            // `never`-returning `fail()` are not fail-open - the scanner reads no types, so it trusts
+            // the helper by name, the same trade the SQL and gate-name heuristics already make.
+            if (
+              !/\b(?:throw|return\s+(?:false|new\s+Response|deny))/s.test(text) &&
+              !/(?:^|[^.\w])(?:fail|deny|reject|forbid|unauthorized|abort)\s*\(/s.test(text)
+            ) {
               const line = tree.getLineAndCharacterOfPosition(node.getStart(tree)).line + 1
               const reviewed = hasReview(lines, line)
               findings.push(