@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/dist/analyze/crawl.d.ts

@@ -0,0 +1,134 @@
+/**
+ * crawl — programmatic middleware-mode crawl (the cold path).
+ *
+ * Boots `createServer({ middlewareMode: true })` — no HTTP port, no route
+ * rendering — and BFS-walks `env.transformRequest(url)` → importedModules
+ * edges from `virtual:timber-rsc-entry`, then from every discovered
+ * `'use client'` boundary through the SSR environment. This reuses Vite's
+ * actual resolution (aliases, tsconfig paths, react-server export
+ * conditions, virtual modules), so it cannot drift from what dev or the
+ * build does; hand-rolled resolution was evaluated and rejected
+ * (design/47 §"Verified Prototype Findings").
+ *
+ * Cost model (design/47 §6): 2.5 s on small apps to ~10 s on dep-heavy
+ * plugin stacks, with a transient ~1.3 GB RSS — callers MUST run this in
+ * a short-lived child process (see crawl-entry.ts) and cache the
+ * classification output, not the Vite transforms. The crawl always
+ * covers the full project: one crawl per project state, never per
+ * question — marginal per-file cost is ~zero once booted.
+ *
+ * `TIMBER_ANALYZE=1` is set before the server boots so platform dev
+ * plugins (wrangler bindings — a measured ~6.8 s remote-bindings
+ * handshake on website) skip work the crawl never needs: classification
+ * wants import edges, not live Cloudflare connections.
+ *
+ * Design docs: 47-module-environment-tooling.md §6, §8.
+ */
+import { type ModuleClassification } from './classify.ts';
+import { type ImportChain } from './chains.ts';
+import { type Poisoning } from './poison-scan.ts';
+/**
+ * Marker preceding the JSON report on crawl-entry's stdout. Lives here
+ * (not in crawl-entry.ts) so consumers can import it without executing
+ * the child entry's main().
+ */
+export declare const CRAWL_RESULT_MARKER = "__TIMBER_CRAWL_RESULT__";
+export interface CrawlOptions {
+    /** Project root (the app directory containing vite.config). */
+    root: string;
+    /** Explicit Vite config file; discovered from root when omitted. */
+    configFile?: string;
+    /** Overall crawl deadline. Default 120s. */
+    timeoutMs?: number;
+}
+export interface CrawlError {
+    /** 'scan' covers disk-scan and directive-read failures. */
+    environment: 'rsc' | 'ssr' | 'scan';
+    id: string;
+    message: string;
+}
+/**
+ * One project file's full graph answer — the classification plus the
+ * remaining JSON-contract fields (`boundary`, `chains`, `poisonings`)
+ * that need the open graphs / original sources to compute. This is the
+ * per-module unit `timber graph` caches and serves.
+ */
+export interface GraphModuleReport extends ModuleClassification {
+    /** True when the file itself carries `'use client'`. */
+    boundary: boolean;
+    /** Boundary-aware import chains (design/47 §7); [] when in no graph. */
+    chains: ImportChain[];
+    /** Report-only poisoning conflicts (design/47 §3); [] when clean. */
+    poisonings: Poisoning[];
+}
+export interface CrawlReport {
+    root: string;
+    /**
+     * True when the crawl deadline expired mid-walk — the report is
+     * truncated, not wrong, and the condition is transient (a slow
+     * machine, a cold dep-optimizer). Consumers must not cache an
+     * incomplete report: with unchanged files it would be served forever,
+     * never retrying after the transient cause cleared. Deterministic
+     * per-module transform failures do NOT set this — they recur on
+     * retry, so caching them is correct.
+     */
+    incomplete: boolean;
+    /** Classification of every project file, sorted by path. */
+    modules: GraphModuleReport[];
+    /**
+     * Transform failures encountered during the BFS. These are classified,
+     * not swallowed — CSS/asset URLs and non-transformable modules land
+     * here (44 on website in the §6 measurement) and the crawl continues.
+     */
+    errors: CrawlError[];
+    stats: {
+        rscGraphModules: number;
+        ssrGraphModules: number;
+        projectFiles: number;
+        durationMs: number;
+    };
+}
+/** Duck-typed view of the Vite dev environment surface the crawl uses. */
+export interface CrawlEnvironment {
+    transformRequest(url: string): Promise<unknown>;
+    moduleGraph: {
+        getModuleByUrl(url: string): Promise<CrawlModuleNode | undefined>;
+    };
+}
+interface CrawlModuleNode {
+    id: string | null;
+    url: string;
+    file: string | null;
+    importedModules: Set<CrawlModuleNode>;
+    transformResult: unknown;
+}
+interface EnvCrawlResult {
+    /** Absolute paths of project files reached in this environment. */
+    projectFiles: Set<string>;
+    /** Project files whose own transform failed (membership unconfirmed subtree). */
+    failedFiles: Set<string>;
+    /** Total graph modules visited (project + deps + virtual). */
+    visited: number;
+    /** The deadline expired mid-walk — the result is truncated. */
+    deadlineHit: boolean;
+}
+/**
+ * BFS one environment from the given seed URLs, transforming every
+ * discovered module unconditionally. Transforming (rather than reading
+ * live graphs) is what closes the §8 blind spot: modules behind
+ * unexecuted dynamic imports are transformed here like any other edge.
+ *
+ * Exported for tests (deadline behavior is exercised with a fake env).
+ */
+export declare function crawlEnvironment(env: CrawlEnvironment, envName: 'rsc' | 'ssr', seeds: string[], root: string, deadlineAt: number, errors: CrawlError[], extensions?: RegExp): Promise<EnvCrawlResult>;
+/**
+ * Crawl a project cold and classify every project file.
+ *
+ * Boots a middleware-mode Vite server with the app's own config (all
+ * timber plugins, real resolution), crawls the RSC graph from the entry,
+ * detects directives from original sources, crawls the SSR graph from
+ * every `'use client'` boundary, and intersects the memberships.
+ */
+export declare function crawlProject(options: CrawlOptions): Promise<CrawlReport>;
+export {};
+//# sourceMappingURL=crawl.d.ts.map

package/dist/analyze/crawl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crawl.d.ts","sourceRoot":"","sources":["../../src/analyze/crawl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAuC,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,EAIL,KAAK,SAAS,EACf,MAAM,kBAAkB,CAAC;AAK1B;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,4BAA4B,CAAC;AAE7D,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,2DAA2D;IAC3D,WAAW,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAkB,SAAQ,oBAAoB;IAC7D,wDAAwD;IACxD,QAAQ,EAAE,OAAO,CAAC;IAClB,wEAAwE;IACxE,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,qEAAqE;IACrE,UAAU,EAAE,SAAS,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;OAQG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB,4DAA4D;IAC5D,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B;;;;OAIG;IACH,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,KAAK,EAAE;QACL,eAAe,EAAE,MAAM,CAAC;QACxB,eAAe,EAAE,MAAM,CAAC;QACxB,YAAY,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;CACH;AA+BD,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChD,WAAW,EAAE;QACX,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAAC;KACnE,CAAC;CACH;AAED,UAAU,eAAe;IACvB,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,eAAe,EAAE,GAAG,CAAC,eAAe,CAAC,CAAC;IACtC,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,UAAU,cAAc;IACtB,mEAAmE;IACnE,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,iFAAiF;IACjF,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,WAAW,EAAE,OAAO,CAAC;CACtB;AAiBD;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,gBAAgB,EACrB,OAAO,EAAE,KAAK,GAAG,KAAK,EACtB,KAAK,EAAE,MAAM,EAAE,EACf,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,UAAU,EAAE,EACpB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,cAAc,CAAC,CAsDzB;AAuCD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAoM9E"}

package/dist/analyze/graph-cache.d.ts

@@ -0,0 +1,104 @@
+/**
+ * graph-cache — the mtime-keyed output cache for `timber graph`.
+ *
+ * The cold crawl costs seconds (design/47 §6) and its cost is setup +
+ * dependency compilation, not project-file count — so the cacheable
+ * unit is the classification OUTPUT, never Vite's transforms. One
+ * crawl per project state: the first question after a clone pays for
+ * the crawl, every subsequent question is a cache hit until the
+ * project changes.
+ *
+ * Validity is a fingerprint over (path, mtime, size) of every project
+ * source file — the same disk walk the crawl itself uses (scan.ts), so
+ * cache coverage and crawl coverage cannot drift — plus the config
+ * files and the nearest lockfile, since dependency changes change
+ * resolution (export conditions can flip a file's environment without
+ * touching project code).
+ *
+ * Deliberately vite-free: a cache hit answers without importing Vite.
+ *
+ * Design docs: 47-module-environment-tooling.md §"Cold-path policy".
+ */
+import type { CrawlReport } from './crawl.ts';
+/**
+ * JSON contract version (design/47 §9) — one constant for every
+ * frontend (CLI and dev-server endpoint), so the two cannot drift.
+ * Lives here rather than graph-command.ts because this module is
+ * vite-free and both frontends already depend on the analyze core.
+ */
+export declare const GRAPH_JSON_VERSION = 1;
+/** Bump when the report shape or fingerprint inputs change. */
+export declare const GRAPH_CACHE_VERSION = 2;
+export interface GraphCacheFile {
+    version: number;
+    fingerprint: string;
+    /** The Vite config file the cached crawl booted with. */
+    configFile: string;
+    /**
+     * The resolved pageExtensions from the timber config at crawl time.
+     * Stored so the vite-free hit path can reproduce the same scan
+     * extension set (custom extensions like 'foo' must be admitted on
+     * both the write and the hit path, or the fingerprint disagrees
+     * with what was cached).
+     */
+    pageExtensions?: string[];
+    /**
+     * Files the fingerprint tracks BEYOND the disk scan, discovered at
+     * crawl time: Vite's `configFileDependencies` (a config helper
+     * imported from outside the app root can reshape the whole app) and
+     * every file the report itself classifies (the graph can reach files
+     * the scan skips — `app/.well-known/page.tsx`, a route under a
+     * directory named `dist`). The hit path re-stats exactly this list,
+     * so an edit to any of them misses the cache.
+     */
+    trackedExtras: string[];
+    report: CrawlReport;
+}
+/**
+ * Follow a tsconfig/jsconfig `extends` chain, returning every file on
+ * it (the start file included). A base config outside the app —
+ * `"extends": "../tsconfig.base.json"` with a `paths` mapping — can
+ * reshape Vite's resolution without touching anything else the
+ * fingerprint tracks. Parsing is a targeted regex, not JSONC: tsconfig
+ * allows comments, and all we need is the `extends` value. Package
+ * specifiers resolve through Node resolution (an approximation of
+ * TypeScript's — the `.json` append covers the common shapes): a
+ * WORKSPACE package like `@repo/tsconfig/base.json` is a link, so its
+ * edits change neither the lockfile nor any scanned file and must be
+ * fingerprinted directly; registry packages resolve too, harmlessly.
+ * Cycles and unresolvable targets just end the walk (bounded at 16).
+ */
+/**
+ * Strip JSONC comments so a commented-out `"extends"` line cannot
+ * shadow the real one. String-aware: comment markers inside string
+ * literals (a path containing `//`) survive.
+ */
+export declare function stripJsonComments(raw: string): string;
+/** `path\0mtime\0size` entries for a file list; absent files contribute nothing. */
+export declare function fingerprintEntriesForFiles(files: Iterable<string>): Promise<string[]>;
+/**
+ * Entries for the scan-derived base set: project source files, the
+ * config, root manifests, and the nearest lockfile. Scan failures are
+ * folded into the entry list rather than thrown: an unreadable
+ * directory changes the answer's completeness, so it must change the
+ * key too.
+ */
+export declare function collectBaseFingerprintEntries(root: string, configFile: string, pageExtensions?: readonly string[]): Promise<string[]>;
+/** Hash an entry list order-independently. */
+export declare function hashFingerprintEntries(entries: string[]): string;
+/**
+ * Fingerprint the project state `timber graph`'s answers depend on:
+ * the scan-derived base set plus `extraFiles` (the cache's
+ * trackedExtras on the hit path; config dependencies + report files on
+ * the write path).
+ */
+export declare function computeProjectFingerprint(root: string, configFile: string, extraFiles?: readonly string[], pageExtensions?: readonly string[]): Promise<string>;
+/** Read the cache file; anything unreadable or version-mismatched is a miss. */
+export declare function readGraphCache(root: string): Promise<GraphCacheFile | null>;
+/**
+ * Write the cache atomically (temp file + rename) so a concurrent
+ * reader — parallel agent invocations are the expected workload —
+ * never sees a torn JSON file.
+ */
+export declare function writeGraphCache(root: string, cache: GraphCacheFile): Promise<void>;
+//# sourceMappingURL=graph-cache.d.ts.map

package/dist/analyze/graph-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-cache.d.ts","sourceRoot":"","sources":["../../src/analyze/graph-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAOH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAuCrC,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B;;;;;;;;OAQG;IACH,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;;;;;;;;;;;GAaG;AACH;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA4BrD;AAsED,oFAAoF;AACpF,wBAAsB,0BAA0B,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAY3F;AAED;;;;;;GAMG;AACH,wBAAsB,6BAA6B,CACjD,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,GACjC,OAAO,CAAC,MAAM,EAAE,CAAC,CA4BnB;AAED,8CAA8C;AAC9C,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAGhE;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,UAAU,GAAE,SAAS,MAAM,EAAO,EAClC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,GACjC,OAAO,CAAC,MAAM,CAAC,CAIjB;AAED,gFAAgF;AAChF,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAkBjF;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAIxF"}

package/dist/analyze/graph-command.d.ts

@@ -0,0 +1,43 @@
+/**
+ * graph-command — `timber graph <file> [--json] [--all --json]`.
+ *
+ * Answers "what environment(s) does this file run in?" by delegating
+ * to a running dev server when one is discovered (milliseconds), and
+ * falling back to the cold crawl + mtime-keyed cache otherwise
+ * (design/47 §5b). Dev-server responses are NOT cached in the mtime
+ * cache: live answers may include real browser-graph data.
+ *
+ * Config anchoring deliberately diverges from `check`/`build`: those
+ * discover the Vite config from the cwd ("the app here"), which is
+ * wrong for a file-addressed command invoked from a monorepo root —
+ * cwd anchoring would select the wrong app. `graph` walks UP from the
+ * target file's directory to the nearest Vite config and resolves from
+ * there, so the file's own app answers. `--config` overrides, same as
+ * everywhere else.
+ *
+ * Cold-path policy: a cold single-file query runs the full-project
+ * crawl (`--all` internally) and caches the entire report — one crawl
+ * per project state, every subsequent question a cache hit. The
+ * cache-hit path never imports Vite.
+ */
+export type GraphSource = 'dev-server' | 'static-scan';
+export interface GraphOptions {
+    /** Target file; required unless `all`. */
+    file?: string;
+    /** Explicit Vite config path (overrides the walk-up discovery). */
+    config?: string;
+    json: boolean;
+    all: boolean;
+}
+/**
+ * Walk up from `startDir` to the nearest directory containing a Vite
+ * config file. Returns the config's absolute path, or null at the
+ * filesystem root.
+ */
+export declare function findViteConfigUpward(startDir: string): string | null;
+/**
+ * Run `timber graph`. Throws with actionable messages; the CLI's main()
+ * prints and exits nonzero.
+ */
+export declare function runGraph(options: GraphOptions): Promise<void>;
+//# sourceMappingURL=graph-command.d.ts.map

package/dist/analyze/graph-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-command.d.ts","sourceRoot":"","sources":["../../src/analyze/graph-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA4BH,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,aAAa,CAAC;AA0BvD,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,EAAE,OAAO,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAWpE;AAohBD;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA6HnE"}