@nifrajs/web 3.1.0 → 3.2.0

package/src/internal/parity.ts

@@ -6,9 +6,9 @@
  * manifest normalization so those callers cannot quietly grow separate rules.
  */
 
-import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs"
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs"
 import { lstat, realpath, stat } from "node:fs/promises"
-import { dirname, join, relative, resolve, sep } from "node:path"
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
 import {
   matchesSingleCopyDeclaration,
   readSingleCopyDeclaration,
@@ -32,6 +32,12 @@ const MAX_LINK_PROBES = 4_096
 export interface IdentityParityCopy {
   readonly version: string
   readonly path: string
+  /**
+   * The resolved realpath of the copy. `path` is display-relative to the invoked directory, which
+   * reads well in a report but cannot be pasted into a resolver or an editor from anywhere else.
+   * Absent on a finding built by hand (a test fixture, an older cached result).
+   */
+  readonly absolutePath?: string
   readonly importers: readonly string[]
 }
 
@@ -156,14 +162,121 @@ export interface DevelopmentParityInput {
 }
 
 const SOURCE_EXTENSIONS = /\.(?:c|m)?(?:j|t)sx?$|\.(?:mdx|svelte|vue)$/
-/** A first-party reference to a stylesheet by an explicit path specifier. Covers static `import`,
- * re-export `from`, dynamic `import(...)`, and `require(...)`. It stays deliberately *sound*: it only
- * matches when a stylesheet specifier genuinely exists, never on an unreferenced `.css` file in the
- * tree. With the css parity comparison now directional (a scanner miss passes, a false positive fails),
- * a loose pattern would fail correct apps. Specifiers that cannot end in a stylesheet extension (a bare
- * package `exports` subpath) stay unreachable without a resolver; those fall in the passing direction. */
-const CSS_IMPORT =
-  /(?:import\s+(?:[^"']+\s+from\s+)?|from\s+|(?:import|require)\s*\(\s*)["'][^"']+\.(?:css|scss|sass|less|styl)(?:\?[^"']*)?["']/i
+/** A stylesheet path that the source scanner can prove is a real explicit import. */
+const CSS_SPECIFIER = /\.(?:css|scss|sass|less|styl)(?:\?[^"'`]*)?$/i
+
+type CssToken =
+  | { readonly kind: "identifier"; readonly value: string; readonly lineStart: boolean }
+  | { readonly kind: "string"; readonly value: string }
+  | { readonly kind: "punctuator"; readonly value: string }
+
+/**
+ * Tokenize only the small part of TypeScript/JS needed for the CSS contract.
+ *
+ * A regex over source text is not sound here: documentation routes contain code examples such as
+ * `import "./app.css"` in template literals, and comments can contain the same text. Those are not
+ * imports and must not make a style-free production build fail. This intentionally conservative lexer
+ * drops comments and complete template literals (including `${...}` expressions); missing a stylesheet
+ * is the passing direction of this parity check, while claiming one that is not imported is not.
+ */
+const cssTokens = (source: string): readonly CssToken[] => {
+  const tokens: CssToken[] = []
+  let lineStart = true
+  for (let index = 0; index < source.length; ) {
+    const char = source[index]
+    if (char === undefined) break
+    if (/\s/.test(char)) {
+      if (char === "\n" || char === "\r") lineStart = true
+      index++
+      continue
+    }
+    if (char === "/" && source[index + 1] === "/") {
+      index += 2
+      while (index < source.length && source[index] !== "\n") index++
+      continue
+    }
+    if (char === "/" && source[index + 1] === "*") {
+      const commentStart = index
+      index += 2
+      while (index < source.length && !(source[index] === "*" && source[index + 1] === "/")) index++
+      index = Math.min(source.length, index + 2)
+      if (/[\r\n]/.test(source.slice(commentStart, index))) lineStart = true
+      continue
+    }
+    if (char === "`") {
+      const templateStart = index
+      index++
+      while (index < source.length) {
+        const templateChar = source[index]
+        if (templateChar === "\\") {
+          index += 2
+          continue
+        }
+        index++
+        if (templateChar === "`") break
+      }
+      lineStart = /[\r\n]/.test(source.slice(templateStart, index))
+      continue
+    }
+    if (char === '"' || char === "'") {
+      const quote = char
+      const start = ++index
+      while (index < source.length) {
+        const stringChar = source[index]
+        if (stringChar === "\\") {
+          index += 2
+          continue
+        }
+        index++
+        if (stringChar === quote) break
+      }
+      tokens.push({ kind: "string", value: source.slice(start, Math.max(start, index - 1)) })
+      lineStart = false
+      continue
+    }
+    if (/[A-Za-z_$]/.test(char)) {
+      const start = index++
+      while (index < source.length && /[A-Za-z0-9_$]/.test(source[index] ?? "")) index++
+      tokens.push({ kind: "identifier", value: source.slice(start, index), lineStart })
+      lineStart = false
+      continue
+    }
+    tokens.push({ kind: "punctuator", value: char })
+    lineStart = false
+    index++
+  }
+  return tokens
+}
+
+const isStylesheetToken = (token: CssToken | undefined): boolean =>
+  token?.kind === "string" && CSS_SPECIFIER.test(token.value)
+
+/** Detect static imports, re-exports, literal dynamic imports, and literal require calls. */
+const hasStylesheetImport = (source: string): boolean => {
+  const tokens = cssTokens(source)
+  for (let index = 0; index < tokens.length; index++) {
+    const token = tokens[index]
+    if (token?.kind !== "identifier") continue
+    const next = tokens[index + 1]
+    if (token.value === "import") {
+      if (token.lineStart && isStylesheetToken(next)) return true
+      if (next?.value === "(" && isStylesheetToken(tokens[index + 2])) return true
+    }
+    if (token.value === "require" && next?.value === "(" && isStylesheetToken(tokens[index + 2]))
+      return true
+    if (token.value === "from" && isStylesheetToken(next)) {
+      for (let previous = index - 1; previous >= 0; previous--) {
+        const candidate = tokens[previous]
+        if (candidate?.kind === "identifier" && candidate.lineStart) {
+          if (candidate.value === "import" || candidate.value === "export") return true
+          break
+        }
+        if (candidate?.value === ";") break
+      }
+    }
+  }
+  return false
+}
 /** A single-file-component `<style>` block (Svelte/Vue). The bundler extracts these into the app
  * stylesheet even though no `import "...css"` statement exists, so the dev contract must count them
  * or a scoped-style component would look style-free next to a production manifest that carries css. */
@@ -219,8 +332,85 @@ const pathExists = (path: string): Promise<boolean> =>
     () => false,
   )
 
-const pathInside = (root: string, path: string): boolean =>
-  path === root || path.startsWith(root.endsWith(sep) ? root : `${root}${sep}`)
+/** The real path, or the input when it cannot be resolved. Roots are compared against each other and
+ * printed side by side, so they have to be normalized the same way (`/var` vs `/private/var`). */
+const realpathOrSelf = (path: string): string => {
+  try {
+    // The native Windows resolver is the one that knows how to expand 8.3 aliases such as
+    // `RUNNER~1`. The portable resolver can preserve the spelling it was given, which makes two
+    // handles to the same checkout look like different install roots.
+    return process.platform === "win32" ? realpathSync.native(path) : realpathSync(path)
+  } catch {
+    return path
+  }
+}
+
+/** Canonical comparison form for containment. Windows paths are case-insensitive and CI can expose
+ * the same directory once through a short name (`RUNNER~1`) and once through its long name. */
+const comparisonPath = (path: string): string => {
+  const resolved = realpathOrSelf(resolve(path))
+  const native = resolved.replaceAll("/", sep)
+  return process.platform === "win32" ? native.toLowerCase() : native
+}
+
+/**
+ * Windows may expose the same directory through a long path and an 8.3 short path even after
+ * `realpathSync` has normalized both inputs. When the lexical comparison above says "outside", walk
+ * the target's existing ancestors and compare the filesystem identity of each one. `statSync` with
+ * bigint fields avoids truncating Windows file IDs, and a missing identity fails closed.
+ */
+const pathInsideByFilesystemIdentity = (root: string, path: string): boolean => {
+  if (process.platform !== "win32") return false
+  const rootIdentity = (() => {
+    try {
+      const info = statSync(realpathOrSelf(resolve(root)), { bigint: true })
+      if (info.ino === 0n) return undefined
+      return { dev: info.dev, ino: info.ino }
+    } catch {
+      try {
+        const info = statSync(realpathOrSelf(resolve(root)))
+        if (info.ino === 0) return undefined
+        return { dev: BigInt(info.dev), ino: BigInt(info.ino) }
+      } catch {
+        return undefined
+      }
+    }
+  })()
+  if (rootIdentity === undefined) return false
+
+  let current = realpathOrSelf(resolve(path))
+  for (;;) {
+    try {
+      const info = statSync(current, { bigint: true })
+      if (info.ino !== 0n && info.dev === rootIdentity.dev && info.ino === rootIdentity.ino)
+        return true
+    } catch {
+      try {
+        const info = statSync(current)
+        if (
+          info.ino !== 0 &&
+          BigInt(info.dev) === rootIdentity.dev &&
+          BigInt(info.ino) === rootIdentity.ino
+        )
+          return true
+      } catch {
+        // A non-existent leaf can still have an existing parent. Keep walking; if no ancestor can
+        // prove containment, the answer remains false rather than trusting a spelling alone.
+      }
+    }
+    const parent = dirname(current)
+    if (parent === current) return false
+    current = parent
+  }
+}
+
+export const pathInside = (root: string, path: string): boolean => {
+  const distance = relative(comparisonPath(root), comparisonPath(path))
+  const lexicallyInside =
+    distance === "" ||
+    (distance !== ".." && !distance.startsWith(`..${sep}`) && !isAbsolute(distance))
+  return lexicallyInside || pathInsideByFilesystemIdentity(root, path)
+}
 
 const workspaceContains = async (
   root: string,
@@ -233,27 +423,12 @@ const workspaceContains = async (
     for await (const match of new Bun.Glob(packagePattern).scan({ cwd: root, dot: false })) {
       if (match.split(/[\\/]/).includes("node_modules")) continue
       const packageRoot = resolve(root, dirname(match))
-      const targetRelative = relative(packageRoot, target)
-      if (
-        targetRelative === "" ||
-        (!targetRelative.startsWith(`..${sep}`) && targetRelative !== "..")
-      )
-        return true
+      if (pathInside(packageRoot, target)) return true
     }
   }
   return false
 }
 
-/** The real path, or the input when it cannot be resolved. Roots are compared against each other and
- * printed side by side, so they have to be normalized the same way (`/var` vs `/private/var`). */
-const realpathOrSelf = (path: string): string => {
-  try {
-    return realpathSync(path)
-  } catch {
-    return path
-  }
-}
-
 /** Resolve the workspace root once, even when the caller starts in a workspace package. */
 export async function resolveParityWorkspaceRoot(
   start: string,
@@ -392,7 +567,7 @@ const linkedPackageRoots = async (
 
 export const displayPath = (cwd: string, path: string): string => {
   const rel = relative(cwd, path)
-  return rel === "" ? "." : rel
+  return rel === "" ? "." : rel.replaceAll("\\", "/")
 }
 
 /**
@@ -465,7 +640,7 @@ const describeScope = (
   if (requestedRoot === scanRoot) return undefined
   const outside = paths.filter((path) => !pathInside(requestedRoot, path))
   if (outside.length === 0) return undefined
-  const here = relative(scanRoot, requestedRoot) || "."
+  const here = displayPath(scanRoot, requestedRoot) || "."
   return `${outside.length} of these copies ${outside.length === 1 ? "is" : "are"} outside ${here}, so this fails every build in the workspace, including apps that never import the package. The scan is anchored on the workspace on purpose: a copy reached through a workspace-linked dependency cannot be seen from ${here} alone, and scoping to it would miss the case this check exists for. Fix the copies where they live, or declare the package single-copy.`
 }
 
@@ -577,6 +752,7 @@ export async function collectIdentityParity(
       .map(([path, copy]) => ({
         version: copy.version,
         path: displayPath(requestedRoot, path),
+        absolutePath: path,
         importers: [...copy.importers].sort(),
       }))
     const topology = describeTopology(requestedRoot, scanRoot, absolutePaths)
@@ -775,7 +951,11 @@ const sourceFilesUnder = (root: string): readonly string[] => {
   const files: string[] = []
   const walk = (current: string): void => {
     for (const entry of readdirSync(current, { withFileTypes: true })) {
-      if (["node_modules", "dist", "build", ".git", ".nifra", "coverage"].includes(entry.name))
+      if (
+        ["node_modules", "dist", "dist-node", "build", ".git", ".nifra", "coverage"].includes(
+          entry.name,
+        )
+      )
         continue
       const path = join(current, entry.name)
       if (entry.isDirectory()) walk(path)
@@ -814,7 +994,7 @@ export function collectDevelopmentParityInput(
   const sourceRoot = dirname(resolve(routesDir))
   const css = sourceFilesUnder(sourceRoot).some((file) => {
     const content = readFileSync(file, "utf8")
-    return CSS_IMPORT.test(content) || (isSingleFileComponent(file) && SFC_STYLE.test(content))
+    return hasStylesheetImport(content) || (isSingleFileComponent(file) && SFC_STYLE.test(content))
   })
     ? ["css:present"]
     : []
@@ -855,9 +1035,9 @@ export function compareManifestParity(
   return differences
 }
 
-/** The forms `CSS_IMPORT` cannot see, quoted in a css parity failure so the reader knows where to look. */
+/** The forms the source scanner cannot prove, quoted in a css parity failure so the reader knows where to look. */
 const CSS_SCANNER_BLIND_SPOTS =
-  "a dynamic import(), a bare package subpath (exports), require(), an @import inside a stylesheet, or plugin-injected css"
+  "a bare package subpath (exports), an @import inside a stylesheet, template interpolation, or plugin-injected css"
 
 const symmetricDifference = (
   a: readonly string[],
@@ -881,7 +1061,7 @@ function explainParityDifference(
     const shipped = (production.css ?? []).join(", ")
     const where = development.sourceRoot === undefined ? "" : ` under ${development.sourceRoot}`
     return (
-      `css: production ships [${shipped || "(none)"}] but the development scanner found no static ` +
+      `css: production ships [${shipped || "(none)"}] but the development scanner found a static ` +
       `stylesheet import${where} - it is blind to ${CSS_SCANNER_BLIND_SPOTS}`
     )
   }