@neat.is/core 0.4.9 → 0.4.11

package/dist/cli.js

@@ -41,7 +41,7 @@ import {
   setStatus,
   startPersistLoop,
   startStalenessLoop
-} from "./chunk-J5CEKCTR.js";
+} from "./chunk-OJHI33LD.js";
 import {
   startOtelGrpcReceiver
 } from "./chunk-3QCRUEQD.js";
@@ -424,6 +424,7 @@ async function startWatch(graph, opts) {
   const onSpan = makeSpanHandler({
     graph,
     errorsPath: opts.errorsPath,
+    scanPath: opts.scanPath,
     project: projectName,
     writeErrorEventInline: false,
     onPolicyTrigger
@@ -438,6 +439,7 @@ async function startWatch(graph, opts) {
     const onSpanGrpc = makeSpanHandler({
       graph,
       errorsPath: opts.errorsPath,
+      scanPath: opts.scanPath,
       project: projectName,
       onPolicyTrigger
     });
@@ -697,13 +699,20 @@ import path4 from "path";
 
 // src/installers/templates.ts
 var OTEL_INIT_HEADER = "// Generated by `neat init --apply` (ADR-069). OpenTelemetry auto-instrumentation hook.";
-var OTEL_INIT_STAMP = "// neat-template-version: 3 \u2014 file-first call-site capture (ADR-089) + OTLP bearer auth (#410).";
+var OTEL_INIT_STAMP = "// neat-template-version: 4 \u2014 layered file-first capture (ADR-090): stack walk + handler-entry + off-stack facades.";
 var OTEL_OTLP_HEADERS_JS = "if (process.env.NEAT_OTEL_TOKEN) process.env.OTEL_EXPORTER_OTLP_HEADERS ||= 'Authorization=Bearer ' + process.env.NEAT_OTEL_TOKEN";
-function neatCallsiteProcessorSource(ts) {
-  const stackT = ts ? ": string" : "";
+function neatCaptureSource(ts) {
   const spanT = ts ? ": any" : "";
   const strOpt = ts ? ": string | undefined" : "";
-  return `function __neatPickUserFrame(stack${stackT}) {
+  const anyT = ts ? ": any" : "";
+  const fnT = ts ? ": any" : "";
+  const arrAny = ts ? ": any[]" : "";
+  return `// Context key shared by the facade/handler wraps (writers) and the
+// processor fallback (reader). Symbol.for keeps it stable even if the wraps
+// and the processor end up in different module instances.
+const NEAT_USER_FRAME = Symbol.for('neat.user-frame')
+
+function __neatPickUserFrame(stack${strOpt}) {
   const lines = String(stack || '').split('\\n')
   for (let i = 0; i < lines.length; i++) {
     const raw = lines[i].trim()
@@ -712,6 +721,9 @@ function neatCallsiteProcessorSource(ts) {
     if (raw.indexOf('@opentelemetry') !== -1) continue
     if (raw.indexOf('node:') !== -1) continue
     if (raw.indexOf('NeatCallSiteSpanProcessor') !== -1) continue
+    // Skip NEAT's own inlined wraps/helpers (all carry the __neat prefix) so a
+    // facade frame never masquerades as the user's call site.
+    if (raw.indexOf('__neat') !== -1) continue
     const bodyText = raw.slice(3)
     const loc = bodyText.match(/:(\\d+):(\\d+)\\)?$/)
     if (!loc) continue
@@ -733,32 +745,245 @@ function neatCallsiteProcessorSource(ts) {
   return null
 }
 
+// Layer 2/3 fallback source: the frame a handler-entry or facade wrap pushed
+// into context. Reads the span's own parent context first, then the active
+// context \u2014 the capture spike confirmed both return the value for undici.
+function __neatFrameFromContext(parentContext${anyT}) {
+  try {
+    const fromParent =
+      parentContext && typeof parentContext.getValue === 'function'
+        ? parentContext.getValue(NEAT_USER_FRAME)
+        : undefined
+    return fromParent || context.active().getValue(NEAT_USER_FRAME) || null
+  } catch (_e) {
+    return null
+  }
+}
+
+function __neatSetCodeAttrs(span${spanT}, frame${anyT}) {
+  span.setAttribute('code.filepath', frame.filepath)
+  if (typeof frame.lineno === 'number') span.setAttribute('code.lineno', frame.lineno)
+  if (frame.function) span.setAttribute('code.function', frame.function)
+}
+
 class NeatCallSiteSpanProcessor {
-  onStart(span${spanT}) {
+  onStart(span${spanT}, parentContext${anyT}) {
     if (!span || (span.kind !== 2 && span.kind !== 3)) return
-    const frame = __neatPickUserFrame(new Error().stack)
+    // Layer 1 \u2014 synchronous stack walk (sync-wrapper instrumentations).
+    let frame = __neatPickUserFrame(new Error().stack)
+    // Layer 2/3 \u2014 the handler-entry or off-stack-facade frame from context.
+    if (!frame) frame = __neatFrameFromContext(parentContext)
     if (!frame) return
-    span.setAttribute('code.filepath', frame.filepath)
-    if (typeof frame.lineno === 'number') span.setAttribute('code.lineno', frame.lineno)
-    if (frame.function) span.setAttribute('code.function', frame.function)
+    __neatSetCodeAttrs(span, frame)
   }
   onEnd() {}
   forceFlush() { return Promise.resolve() }
   shutdown() { return Promise.resolve() }
+}
+
+// Capture the caller's synchronous frame at the wrap point and run \`fn\` with
+// that frame pushed into the active context (file-awareness.md \xA74 layer 3). An
+// off-stack instrumentation that creates its span inside \`fn\` inherits the
+// frame; the processor reads it via __neatFrameFromContext.
+function __neatRunWithUserFrame(fn${fnT}) {
+  const frame = __neatPickUserFrame(new Error().stack)
+  if (!frame) return fn()
+  return context.with(context.active().setValue(NEAT_USER_FRAME, frame), fn)
+}
+
+// Handler-entry attribution (file-awareness.md \xA74 layer 2). Stamp the framework
+// SERVER span with the handler frame captured at route registration, and push
+// the same frame into context so downstream CLIENT/PRODUCER spans inherit the
+// handler-file floor when their own stack carries none.
+function __neatStampHandler(frame${anyT}, run${fnT}) {
+  try {
+    const active = trace.getActiveSpan()
+    if (active && active.kind === 1 && typeof active.setAttribute === 'function') {
+      __neatSetCodeAttrs(active, frame)
+    }
+  } catch (_e) {}
+  try {
+    return context.with(context.active().setValue(NEAT_USER_FRAME, frame), run)
+  } catch (_e) {
+    return run()
+  }
+}
+
+// require-in-the-middle is a transitive dependency of the OTel instrumentation
+// packages NEAT installs, so it resolves in any instrumented CJS service.
+// Guarded: when it's absent (or the host runs as pure ESM, where require isn't
+// defined) the off-stack/handler wraps degrade to the stack walk + context
+// floor, never to a crash.
+function __neatHook(modules${arrAny}, onload${fnT}) {
+  try {
+    const RITM = require('require-in-the-middle')
+    const Hook = RITM && RITM.Hook ? RITM.Hook : RITM
+    new Hook(modules, { internals: false }, onload)
+    return true
+  } catch (_e) {
+    return false
+  }
+}
+
+// Off-stack facade: Node's built-in fetch / undici. The instrumentation creates
+// the CLIENT span inside a diagnostics_channel handler detached from the
+// caller's stack, so wrap the global so the user frame is in context when the
+// span is created. The capture spike (2026-05-28) validated this on real
+// undici. .name is restored to 'fetch' for ecosystem compatibility; the inner
+// __neat name is what the frame skip keys on.
+function __neatWrapFetch() {
+  try {
+    const g${anyT} = globalThis
+    if (typeof g.fetch === 'function' && !g.fetch.__neatWrapped) {
+      const realFetch = g.fetch
+      // The wrapper keeps its __neat-prefixed name so the frame skip in
+      // __neatPickUserFrame never mistakes the wrapper's own frame for the
+      // user's call site (renaming it to 'fetch' would defeat the skip).
+      const __neatFetch${anyT} = function (input${anyT}, init${anyT}) {
+        return __neatRunWithUserFrame(function () { return realFetch(input, init) })
+      }
+      __neatFetch.__neatWrapped = true
+      g.fetch = __neatFetch
+    }
+  } catch (_e) {}
+}
+
+// Off-stack facade: @prisma/client. Prisma's query engine backdates its spans
+// from Rust, off the caller's stack. Wrap the model methods on the client
+// prototype so the call-site frame (still synchronous at \`prisma.user.find\`)
+// is pushed into context for the engine dispatch.
+function __neatWrapPrisma() {
+  __neatHook(['@prisma/client'], function (exports${anyT}) {
+    try {
+      const Client = exports && exports.PrismaClient
+      if (typeof Client === 'function' && !Client.__neatWrapped) {
+        const ops = ['findUnique','findUniqueOrThrow','findFirst','findFirstOrThrow','findMany','create','createMany','update','updateMany','upsert','delete','deleteMany','count','aggregate','groupBy']
+        const __neatPrismaWrapModel = function (model${anyT}) {
+          if (!model || model.__neatWrapped) return model
+          for (let i = 0; i < ops.length; i++) {
+            const op = ops[i]
+            const orig = model[op]
+            if (typeof orig !== 'function') continue
+            model[op] = function __neatPrismaOp(${ts ? "...args: any[]" : "...args"}) {
+              const self = this
+              return __neatRunWithUserFrame(function () { return orig.apply(self, args) })
+            }
+          }
+          model.__neatWrapped = true
+          return model
+        }
+        const proto = Client.prototype
+        const handler = function (model${anyT}) { return __neatPrismaWrapModel(model) }
+        // Model accessors are lazily created getters on the instance; wrap the
+        // \`$extends\`-free common path by trapping property access via a proxy
+        // on each constructed client.
+        exports.PrismaClient = new Proxy(Client, {
+          construct(Target${anyT}, argList${anyT}, NewTarget${anyT}) {
+            const instance = Reflect.construct(Target, argList, NewTarget)
+            return new Proxy(instance, {
+              get(target${anyT}, prop${anyT}, receiver${anyT}) {
+                const value = Reflect.get(target, prop, receiver)
+                if (value && typeof value === 'object' && typeof prop === 'string' && prop[0] !== '$' && prop[0] !== '_') {
+                  return handler(value)
+                }
+                return value
+              },
+            })
+          },
+        })
+        exports.PrismaClient.__neatWrapped = true
+        void proto
+      }
+    } catch (_e) {}
+    return exports
+  })
+}
+
+// Handler-entry facades. express / connect share the Layer model (each route
+// handler is a function registered on a Router); the wrap captures the
+// registration frame and stamps + propagates it when the handler runs. The
+// registry is the extensibility seam \u2014 koa, fastify (via @fastify/otel),
+// nestjs, restify, and hapi add an entry as their patch surface is wired.
+function __neatWrapConnectStyle(mod${anyT}) {
+  try {
+    // express() returns an app whose route verbs live on Router.prototype and
+    // the application proto; connect apps expose \`use\`. Wrap the registration
+    // verbs so the user handler is wound with its registration frame.
+    const verbs = ['use','get','post','put','delete','patch','all','options','head']
+    const wrapTarget = function (target${anyT}) {
+      if (!target || target.__neatVerbsWrapped) return
+      for (let i = 0; i < verbs.length; i++) {
+        const verb = verbs[i]
+        const orig = target[verb]
+        if (typeof orig !== 'function') continue
+        target[verb] = function __neatVerb(${ts ? "...args: any[]" : "...args"}) {
+          const frame = __neatPickUserFrame(new Error().stack)
+          if (frame) {
+            for (let a = 0; a < args.length; a++) {
+              const h = args[a]
+              if (typeof h === 'function' && !h.__neatHandlerWrapped && h.length <= 4) {
+                const inner = h
+                const __neatHandler${anyT} = function (${ts ? "...hargs: any[]" : "...hargs"}) {
+                  const self = this
+                  return __neatStampHandler(frame, function () { return inner.apply(self, hargs) })
+                }
+                __neatHandler.__neatHandlerWrapped = true
+                args[a] = __neatHandler
+              }
+            }
+          }
+          return orig.apply(this, args)
+        }
+      }
+      target.__neatVerbsWrapped = true
+    }
+    if (mod && mod.Router && mod.Router.prototype) wrapTarget(mod.Router.prototype)
+    if (mod && mod.application) wrapTarget(mod.application)
+    if (mod && mod.prototype) wrapTarget(mod.prototype)
+  } catch (_e) {}
+}
+
+function __neatInstallHandlerEntry() {
+  __neatHook(['express'], function (exports${anyT}) { __neatWrapConnectStyle(exports); return exports })
+  __neatHook(['connect'], function (exports${anyT}) { __neatWrapConnectStyle(exports); return exports })
+}
+
+// Install every off-stack and handler-entry wrap. Called once after sdk.start()
+// \u2014 before user code requires the framework / Prisma modules, so the hooks land
+// on first require. Each wrap is independently guarded.
+function __neatInstallFacades() {
+  __neatWrapFetch()
+  __neatWrapPrisma()
+  __neatInstallHandlerEntry()
 }`;
 }
-var CALLSITE_PROCESSOR_JS = neatCallsiteProcessorSource(false);
-var CALLSITE_PROCESSOR_TS = neatCallsiteProcessorSource(true);
-function neatRegisterCallsiteSource(ts) {
+var CALLSITE_PROCESSOR_JS = neatCaptureSource(false);
+var CALLSITE_PROCESSOR_TS = neatCaptureSource(true);
+function neatWireCaptureSource(ts) {
   const providerT = ts ? ": any" : "";
   return `try {
   const provider${providerT} = trace.getTracerProvider()
   const delegate = provider && typeof provider.getDelegate === 'function' ? provider.getDelegate() : provider
-  if (delegate && typeof delegate.addSpanProcessor === 'function') {
-    delegate.addSpanProcessor(new NeatCallSiteSpanProcessor())
-  }
-} catch {
-  // capture is best-effort; span export is unaffected
+  if (!delegate || typeof delegate.addSpanProcessor !== 'function') {
+    throw new Error('[neat] could not resolve a TracerProvider to attach the call-site processor; file-first OBSERVED capture would be silent (file-awareness.md \xA74)')
+  }
+  const __neatProcessor = new NeatCallSiteSpanProcessor()
+  delegate.addSpanProcessor(__neatProcessor)
+  // Post-init assertion: confirm attachment on providers that expose their
+  // processor list. An un-introspectable provider is trusted (we just called
+  // its addSpanProcessor); a list that exists and lacks our processor throws.
+  const registered = delegate._registeredSpanProcessors
+  if (Array.isArray(registered) && registered.indexOf(__neatProcessor) === -1) {
+    throw new Error('[neat] call-site processor did not attach to the active TracerProvider (file-awareness.md \xA74)')
+  }
+} catch (err) {
+  throw err
+}
+try {
+  __neatInstallFacades()
+} catch (_e) {
+  // Facade install is best-effort: the stack-walk + handler-entry floor still
+  // attribute the sync-wrapper majority even if an off-stack wrap fails.
 }`;
 }
 var OTEL_INIT_CJS = `${OTEL_INIT_HEADER}
@@ -769,7 +994,7 @@ ${OTEL_OTLP_HEADERS_JS}
 
 const { NodeSDK } = require('@opentelemetry/sdk-node')
 const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node')
-const { trace } = require('@opentelemetry/api')
+const { trace, context } = require('@opentelemetry/api')
 
 ${CALLSITE_PROCESSOR_JS}
 
@@ -777,7 +1002,7 @@ const instrumentations = [getNodeAutoInstrumentations()]
 __INSTRUMENTATION_BLOCK__
 const sdk = new NodeSDK({ instrumentations })
 sdk.start()
-${neatRegisterCallsiteSource(false)}
+${neatWireCaptureSource(false)}
 `;
 var OTEL_INIT_ESM = `${OTEL_INIT_HEADER}
 ${OTEL_INIT_STAMP}
@@ -787,7 +1012,7 @@ ${OTEL_OTLP_HEADERS_JS}
 
 import { NodeSDK } from '@opentelemetry/sdk-node'
 import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
-import { trace } from '@opentelemetry/api'
+import { trace, context } from '@opentelemetry/api'
 
 ${CALLSITE_PROCESSOR_JS}
 
@@ -795,17 +1020,22 @@ const instrumentations = [getNodeAutoInstrumentations()]
 __INSTRUMENTATION_BLOCK__
 const sdk = new NodeSDK({ instrumentations })
 sdk.start()
-${neatRegisterCallsiteSource(false)}
+${neatWireCaptureSource(false)}
 `;
 var OTEL_INIT_TS = `${OTEL_INIT_HEADER}
 ${OTEL_INIT_STAMP}
+// @ts-nocheck \u2014 generated runtime shim. The layered capture mechanism uses
+// dynamic patterns (facade wraps, Proxy traps, a createRequire bridge) that a
+// strict user tsconfig would reject; suppressing type-checking here keeps the
+// generated file from breaking the host project's \`tsc\` gate (#427) without
+// constraining the runtime logic. The file is regenerated, never hand-edited.
 process.env.OTEL_SERVICE_NAME ||= '__SERVICE_NAME__'
 process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ||= 'http://localhost:4318/projects/__PROJECT__/v1/traces'
 ${OTEL_OTLP_HEADERS_JS}
 
 import { NodeSDK } from '@opentelemetry/sdk-node'
 import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
-import { trace } from '@opentelemetry/api'
+import { trace, context } from '@opentelemetry/api'
 
 ${CALLSITE_PROCESSOR_TS}
 
@@ -813,7 +1043,7 @@ const instrumentations = [getNodeAutoInstrumentations()]
 __INSTRUMENTATION_BLOCK__
 const sdk = new NodeSDK({ instrumentations })
 sdk.start()
-${neatRegisterCallsiteSource(true)}
+${neatWireCaptureSource(true)}
 `;
 function renderNodeOtelInit(template, serviceName, projectName, registrations = []) {
   const block = registrations.length === 0 ? "" : `