svelte-docinfo 0.1.0

package/dist/vite.js

@@ -0,0 +1,418 @@
+/**
+ * Vite plugin for svelte-docinfo.
+ *
+ * Drives a long-lived `AnalysisSession` against a debounce-batched watcher.
+ * Every file change funnels into a `pendingChanges` Map and flushes via one
+ * `setFiles` + one `query` per debounce window — multi-file editor saves
+ * collapse to a single re-analysis instead of N serialized round-trips.
+ *
+ * The plugin no longer maintains a `fileCache.content` mirror — `setFile`
+ * returns `{changed: boolean}` so HMR invalidation reacts to that flag
+ * directly. `session.list()` / `session.has()` cover owned-set introspection.
+ *
+ * Consumers import the analysis result:
+ *
+ * ```ts
+ * import {modules, diagnostics} from 'virtual:svelte-docinfo';
+ * ```
+ *
+ * For TypeScript support, add to your `app.d.ts`:
+ *
+ * ```ts
+ * /// <reference types="svelte-docinfo/virtual-svelte-docinfo.js" />
+ * ```
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import svelteDocinfo from './vite.js';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     sveltekit(),
+ *     svelteDocinfo(),
+ *   ],
+ * });
+ * ```
+ *
+ * @module
+ */
+import { readFile } from 'node:fs/promises';
+import { createAnalysisSession } from './session.js';
+import { discoverSourceFiles } from './discovery.js';
+import { compactReplacer } from './declaration-helpers.js';
+import { createSourceOptions, isSource, } from './source-config.js';
+import { noDepsResolver } from './dep-resolver.js';
+import { toPosixPath } from './paths.js';
+const VIRTUAL_ID = 'virtual:svelte-docinfo';
+const RESOLVED_VIRTUAL_ID = '\0virtual:svelte-docinfo';
+/** Stable resolver identity for Vite's plugin-container resolver in dev mode. */
+const VITE_DEV_IDENTITY = 'vite-plugin-container';
+/** Stable resolver identity for the Rollup `this.resolve` resolver in build mode. */
+const VITE_BUILD_IDENTITY = 'vite-rollup-build';
+/**
+ * Vite plugin: analyzes TypeScript and Svelte source files via a persistent
+ * `AnalysisSession` and serves the result as `virtual:svelte-docinfo`.
+ *
+ * In dev mode, watches source files and triggers debounced HMR updates on
+ * changes via `setFiles` batches drained from a pending-changes Map.
+ * In build mode, runs analysis once during `buildStart`.
+ */
+const svelteDocinfo = (options = {}) => {
+    const { include, exclude, resolveDependencies = true, discovery, distDir, sourceOptions, onDuplicates, hmrDebounceMs = 100, } = options;
+    let projectRoot;
+    let resolvedSourceOptions;
+    let logger = null;
+    let isDev = false;
+    let modulesJson = '[]';
+    let diagnosticsJson = '[]';
+    let cachedModuleCode = null;
+    let server = null;
+    let session = null;
+    // Discovery diagnostics survive across HMR cycles (the discovery pass only
+    // runs at cold start). Tracked here because the session has no concept of
+    // "discovery" — it ingests files the plugin hands to it.
+    let discoveryDiagnostics = [];
+    // ── Resolver wiring ──────────────────────────────────────────────────────
+    // Dev resolver: server.pluginContainer.resolveId. Stable identity across
+    // the dev session — cache hits work across HMR cycles.
+    const viteDevResolver = {
+        resolve: async (specifier, fromFile) => {
+            try {
+                const r = await server.pluginContainer.resolveId(specifier, fromFile);
+                return r?.id ?? null;
+            }
+            catch {
+                return null;
+            }
+        },
+        identity: VITE_DEV_IDENTITY,
+    };
+    // Build resolver: Rollup `this.resolve` is per-build; we re-bind in
+    // buildStart while keeping a stable identity so cache hits survive
+    // `vite build --watch` rebuilds.
+    let buildResolveFn = null;
+    const buildResolver = {
+        resolve: (specifier, fromFile) => buildResolveFn ? buildResolveFn(specifier, fromFile) : Promise.resolve(null),
+        identity: VITE_BUILD_IDENTITY,
+    };
+    // ── In-flight analysis tracking ─────────────────────────────────────────
+    // Initial analysis runs once in buildStart; HMR flushes run on debounce.
+    // `load()` awaits both so we never serve stale JSON to a freshly-importing
+    // module.
+    let initialPromise = null;
+    let hmrFlushPromise = null;
+    const waitInflight = async () => {
+        if (initialPromise)
+            await initialPromise;
+        if (hmrFlushPromise)
+            await hmrFlushPromise;
+    };
+    // Pending-changes Map: path → newContent (string) or unlink marker (null).
+    // Drained by `flushBatch`; survives across multiple flush cycles when new
+    // events arrive mid-flight.
+    const pendingChanges = new Map();
+    // Per-path event sequence. Watcher events (change/add/unlink) bump the
+    // counter and stamp the path with the new value; async handlers (the
+    // `change` handler awaits readFile before enqueueing) capture the seq at
+    // dispatch and drop their result if a newer event has stamped the path
+    // in between. Without this, an `unlink` arriving during a `change`'s
+    // in-flight readFile gets clobbered when the read resolves with stale
+    // content for a now-deleted file.
+    let eventSeqCounter = 0;
+    const eventSeqs = new Map();
+    const stampEvent = (path) => {
+        const seq = ++eventSeqCounter;
+        eventSeqs.set(path, seq);
+        return seq;
+    };
+    const isLatestEvent = (path, seq) => eventSeqs.get(path) === seq;
+    const buildModuleCode = () => {
+        if (cachedModuleCode !== null)
+            return cachedModuleCode;
+        const lines = [
+            `export const modules = ${modulesJson};`,
+            `export const diagnostics = ${diagnosticsJson};`,
+            `export default {modules, diagnostics};`,
+        ];
+        if (isDev) {
+            lines.push(`if (import.meta.hot) { import.meta.hot.accept(); }`);
+        }
+        cachedModuleCode = lines.join('\n');
+        return cachedModuleCode;
+    };
+    const updateOutputFromQuery = (modules, queryDiagnostics) => {
+        // `JSON.stringify([], compactReplacer)` returns the JS `undefined` because
+        // the replacer strips empty arrays — we embed the JSON into a template
+        // literal where that would interpolate as the literal text `"undefined"`,
+        // so handle the empty-modules case explicitly.
+        const newModulesJson = modules.length === 0 ? '[]' : JSON.stringify(modules, compactReplacer);
+        // Pull cumulative ingest diagnostics from the session — every owned
+        // entry's `ingestDiagnostics` are walked there. Discovery diagnostics
+        // don't pass through the session (file discovery happens before ingest),
+        // so we maintain those separately and merge at publish time.
+        const ingest = session ? session.allIngestDiagnostics() : [];
+        const merged = [...ingest, ...discoveryDiagnostics, ...queryDiagnostics];
+        const newDiagnosticsJson = JSON.stringify(merged);
+        if (newModulesJson === modulesJson && newDiagnosticsJson === diagnosticsJson)
+            return false;
+        modulesJson = newModulesJson;
+        diagnosticsJson = newDiagnosticsJson;
+        cachedModuleCode = null;
+        return true;
+    };
+    const sendHmrInvalidation = () => {
+        if (!server)
+            return;
+        const mod = server.moduleGraph.getModuleById(RESOLVED_VIRTUAL_ID);
+        if (!mod)
+            return;
+        server.moduleGraph.invalidateModule(mod);
+        // Hardcoded Vite URL encoding for \0 prefix on virtual modules.
+        // Not a documented Vite public API — if Vite changes the encoding in a
+        // future release, HMR silently stops firing (initial load still works
+        // through the public resolveId/load hooks). Same pattern as
+        // vite_plugin_fuz_css; update both if Vite exposes a proper API.
+        const hmrPath = '/@id/__x00__virtual:svelte-docinfo';
+        server.hot.send({
+            type: 'update',
+            updates: [
+                {
+                    type: 'js-update',
+                    path: hmrPath,
+                    acceptedPath: hmrPath,
+                    timestamp: Date.now(),
+                },
+            ],
+        });
+    };
+    const errorLog = (err) => {
+        const log = logger ?? { error: (msg) => console.error(msg) };
+        const message = err instanceof Error ? (err.stack ?? err.message) : String(err);
+        log.error(`[svelte-docinfo] ${message}`);
+    };
+    const isWatchedFile = (file) => isSource(file, resolvedSourceOptions);
+    // ── Initial analysis (cold start in buildStart) ──────────────────────────
+    const runInitialAnalysis = async () => {
+        if (!session)
+            return;
+        const { files, diagnostics } = await discoverSourceFiles({
+            sourceOptions: resolvedSourceOptions,
+            include,
+            discovery,
+            distDir,
+            log: logger ?? undefined,
+        });
+        discoveryDiagnostics = diagnostics;
+        await session.setFiles(files);
+        const result = session.query({ onDuplicates, log: logger ?? undefined });
+        updateOutputFromQuery(result.modules, result.diagnostics);
+    };
+    // ── HMR flush: drain pendingChanges via setFiles + query ─────────────────
+    const flushBatch = async () => {
+        if (initialPromise)
+            await initialPromise;
+        if (!session)
+            return;
+        if (pendingChanges.size === 0)
+            return;
+        // Drain. New events arriving during this flush land in pendingChanges
+        // and are picked up by the surrounding while-loop in `scheduleFlush`.
+        const drained = [...pendingChanges];
+        pendingChanges.clear();
+        const toAdd = [];
+        const toDelete = [];
+        for (const [path, content] of drained) {
+            if (content === null)
+                toDelete.push(path);
+            else
+                toAdd.push({ id: path, content });
+        }
+        // Apply deletions first so re-adds (rare but possible: unlink+add same
+        // path within one debounce window) work correctly.
+        for (const path of toDelete)
+            await session.deleteFile(path);
+        let anyChanged = toDelete.length > 0;
+        if (toAdd.length > 0) {
+            const ingest = await session.setFiles(toAdd);
+            if (ingest.changedIds.size > 0)
+                anyChanged = true;
+        }
+        if (!anyChanged)
+            return;
+        // `updateOutputFromQuery` pulls the cumulative ingest diagnostics from
+        // `session.allIngestDiagnostics()` itself — no per-batch survival
+        // tracking needed at the plugin layer.
+        const result = session.query({ onDuplicates, log: logger ?? undefined });
+        const updated = updateOutputFromQuery(result.modules, result.diagnostics);
+        if (updated)
+            sendHmrInvalidation();
+    };
+    const scheduleFlush = () => {
+        if (hmrFlushPromise)
+            return hmrFlushPromise;
+        hmrFlushPromise = (async () => {
+            await new Promise((r) => setTimeout(r, hmrDebounceMs));
+            try {
+                while (pendingChanges.size > 0) {
+                    await flushBatch();
+                }
+            }
+            catch (err) {
+                errorLog(err);
+            }
+            finally {
+                hmrFlushPromise = null;
+            }
+        })();
+        return hmrFlushPromise;
+    };
+    const enqueueChange = (path, content) => {
+        pendingChanges.set(path, content);
+        // `eventSeqs[path]` is no longer needed once the latest event has been
+        // enqueued: any older in-flight handler will fail `isLatestEvent`
+        // against `undefined`, and any newer event will re-stamp on arrival.
+        // Bounds the Map's growth in long-running dev sessions with churn.
+        eventSeqs.delete(path);
+        void scheduleFlush();
+    };
+    return {
+        name: 'vite-plugin-svelte-docinfo',
+        configResolved(config) {
+            projectRoot = options.projectRoot ?? config.root;
+            // `exclude` shortcut overrides `sourceOptions.exclude` (same precedence
+            // as `analyzeFromFiles`).
+            const mergedSourceOptions = exclude !== undefined ? { ...sourceOptions, exclude } : sourceOptions;
+            resolvedSourceOptions = createSourceOptions(projectRoot, mergedSourceOptions);
+            // Reject contradictory discovery config upfront so failures are at
+            // config-load time rather than first analysis.
+            if (discovery === 'exports' && include) {
+                throw new Error("svelte-docinfo: discovery: 'exports' is incompatible with `include`. " +
+                    "Use discovery: 'glob' (with include) or remove include for strict exports mode.");
+            }
+            logger = config.logger;
+            isDev = config.command === 'serve';
+        },
+        async buildStart() {
+            // Choose resolver based on mode; create the session here (after
+            // configResolved set sourceOptions; for dev, after configureServer
+            // set `server`). Identity stable across rebuilds.
+            let sessionResolver;
+            if (!resolveDependencies) {
+                sessionResolver = noDepsResolver;
+            }
+            else if (server) {
+                sessionResolver = viteDevResolver;
+            }
+            else {
+                const ctxResolve = this.resolve.bind(this);
+                buildResolveFn = async (specifier, fromFile) => {
+                    try {
+                        const r = await ctxResolve(specifier, fromFile);
+                        return r?.id ?? null;
+                    }
+                    catch {
+                        return null;
+                    }
+                };
+                sessionResolver = buildResolver;
+            }
+            // Recreate session on each buildStart so `vite build --watch` cycles
+            // get a fresh LS — the document registry across builds isn't a
+            // guaranteed-stable contract from Vite's side.
+            session?.dispose();
+            session = createAnalysisSession({
+                sourceOptions: resolvedSourceOptions,
+                resolveImport: sessionResolver,
+                log: logger ?? undefined,
+            });
+            initialPromise = runInitialAnalysis().finally(() => {
+                initialPromise = null;
+            });
+            await initialPromise;
+        },
+        resolveId(id) {
+            if (id === VIRTUAL_ID)
+                return RESOLVED_VIRTUAL_ID;
+            return undefined;
+        },
+        async load(id) {
+            if (id !== RESOLVED_VIRTUAL_ID)
+                return undefined;
+            // Wait for any in-flight analysis (initial or HMR-triggered) so we
+            // never serve stale JSON to a freshly-importing module.
+            await waitInflight();
+            return buildModuleCode();
+        },
+        configureServer(devServer) {
+            server = devServer;
+            devServer.watcher.on('change', (rawFile) => {
+                // Watcher emits native-separator paths on Windows. Posixify at
+                // the boundary so eventSeqs/pendingChanges keys, isWatchedFile
+                // checks, and downstream session calls all share one canonical id.
+                const file = toPosixPath(rawFile);
+                if (!isWatchedFile(file))
+                    return;
+                // Stamp the event before awaiting readFile so a later unlink/add
+                // for the same path bumps the seq and our resolution drops below.
+                const seq = stampEvent(file);
+                // `.catch(errorLog)` — a sync throw before the first `await` would
+                // otherwise become an unhandled rejection.
+                void (async () => {
+                    // Re-read the file. Editors that touch mtime without changing
+                    // content (formatters saving idempotently) trigger spurious
+                    // events; the session's content-equality check in setFile
+                    // handles that case — `changed: false` short-circuits the
+                    // HMR invalidation.
+                    let newContent;
+                    try {
+                        newContent = await readFile(file, 'utf-8');
+                    }
+                    catch {
+                        // File became unreadable between event and read — treat as unlink.
+                        if (isLatestEvent(file, seq))
+                            enqueueChange(file, null);
+                        return;
+                    }
+                    // A newer event (unlink/add/change) stamped this path while we
+                    // were reading — discard our result so we don't overwrite it
+                    // with stale content (e.g. ingesting a since-deleted file).
+                    if (!isLatestEvent(file, seq))
+                        return;
+                    enqueueChange(file, newContent);
+                })().catch(errorLog);
+            });
+            devServer.watcher.on('add', (rawFile) => {
+                const file = toPosixPath(rawFile);
+                if (!isWatchedFile(file))
+                    return;
+                const seq = stampEvent(file);
+                void (async () => {
+                    try {
+                        const content = await readFile(file, 'utf-8');
+                        if (!isLatestEvent(file, seq))
+                            return;
+                        enqueueChange(file, content);
+                    }
+                    catch (err) {
+                        errorLog(err);
+                    }
+                })().catch(errorLog);
+            });
+            devServer.watcher.on('unlink', (rawFile) => {
+                const file = toPosixPath(rawFile);
+                // Use session.has() as the gate: paths outside source paths were
+                // never owned, so nothing to do.
+                if (!session?.has(file))
+                    return;
+                stampEvent(file);
+                enqueueChange(file, null);
+            });
+            devServer.httpServer?.on('close', () => {
+                session?.dispose();
+                session = null;
+            });
+        },
+    };
+};
+export default svelteDocinfo;

package/package.json

@@ -0,0 +1,131 @@
+{
+  "name": "svelte-docinfo",
+  "version": "0.1.0",
+  "description": "static analysis for TypeScript and Svelte",
+  "glyph": "📜",
+  "logo": "logo.svg",
+  "logo_alt": "a cyan scroll with curling ends",
+  "license": "MIT",
+  "homepage": "https://svelte-docinfo.fuz.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fuzdev/svelte-docinfo.git"
+  },
+  "keywords": [
+    "svelte",
+    "typescript",
+    "documentation",
+    "static-analysis",
+    "api-docs",
+    "component",
+    "jsdoc",
+    "tsdoc",
+    "vite-plugin"
+  ],
+  "scripts": {
+    "start": "gro dev",
+    "dev": "gro dev",
+    "build": "gro build",
+    "check": "gro check",
+    "test": "gro test",
+    "setup-examples": "npm install --prefix examples/api && npm install --prefix examples/vite",
+    "preview": "vite preview",
+    "deploy": "gro deploy"
+  },
+  "type": "module",
+  "bin": {
+    "svelte-docinfo": "dist/main.js"
+  },
+  "dependencies": {
+    "@jridgewell/trace-mapping": "^0.3.25",
+    "commander": "^14.0.3",
+    "es-module-lexer": "^2.0.0",
+    "picomatch": "^4.0.4",
+    "tinyglobby": "^0.2.15",
+    "typescript": "^5.9.3",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "svelte": "^5.0.0",
+    "svelte2tsx": "^0.7.30"
+  },
+  "peerDependenciesMeta": {
+    "svelte": {
+      "optional": true
+    },
+    "svelte2tsx": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@fuzdev/fuz_code": "^0.45.1",
+    "@fuzdev/fuz_css": "^0.60.0",
+    "@fuzdev/fuz_ui": "^0.194.0",
+    "@fuzdev/fuz_util": "^0.61.1",
+    "@fuzdev/gro": "^0.199.1",
+    "@ryanatkn/eslint-config": "^0.12.1",
+    "@sveltejs/acorn-typescript": "^1.0.9",
+    "@sveltejs/adapter-static": "^3.0.10",
+    "@sveltejs/kit": "^2.61.1",
+    "@sveltejs/package": "^2.5.7",
+    "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "@types/estree": "^1.0.8",
+    "@types/node": "^24.10.4",
+    "@types/picomatch": "^4.0.2",
+    "@webref/css": "^8.2.0",
+    "eslint": "^9.39.1",
+    "eslint-plugin-svelte": "^3.13.1",
+    "esm-env": "^1.2.2",
+    "magic-string": "^0.30.21",
+    "prettier": "^3.7.4",
+    "prettier-plugin-svelte": "^3.4.1",
+    "svelte": "^5.55.10",
+    "svelte-check": "^4.3.5",
+    "svelte2tsx": "^0.7.52",
+    "tslib": "^2.8.1",
+    "typescript-eslint": "^8.48.1",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.15",
+    "zimmerframe": "^1.1.4"
+  },
+  "prettier": {
+    "plugins": [
+      "prettier-plugin-svelte"
+    ],
+    "useTabs": true,
+    "printWidth": 100,
+    "singleQuote": true,
+    "bracketSpacing": false,
+    "overrides": [
+      {
+        "files": "package.json",
+        "options": {
+          "useTabs": false
+        }
+      }
+    ]
+  },
+  "sideEffects": [],
+  "files": [
+    "dist",
+    "virtual-svelte-docinfo.d.ts"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./virtual-svelte-docinfo.js": {
+      "types": "./virtual-svelte-docinfo.d.ts"
+    },
+    "./*.js": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./*.ts": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  }
+}

package/virtual-svelte-docinfo.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Type declaration for the `virtual:svelte-docinfo` virtual module
+ * provided by the Vite plugin (`vite.ts`).
+ *
+ * Reference in your `app.d.ts`:
+ *
+ * ```ts
+ * /// <reference types="svelte-docinfo/virtual-svelte-docinfo.js" />
+ * ```
+ *
+ * ## Wire shape vs Zod output shape
+ *
+ * The plugin serializes `modules` through `compactReplacer`, which strips
+ * empty arrays and `false` values to keep the bundle small. So fields like
+ * `declarations`, `members`, `props` that are `.default([])` in the schema
+ * arrive as `undefined` on any module that has none, and `.default(false)`
+ * booleans arrive as `undefined` when false.
+ *
+ * `ModuleJsonInput` (the `z.input` of `ModuleJson`) reflects this — its
+ * default-bearing fields are optional. Consumers either use optional
+ * chaining (`mod.declarations?.length`) or run the value through
+ * `AnalyzeResultJson.parse({modules, diagnostics})` to restore defaults.
+ *
+ * `diagnostics` is serialized without the replacer, so the array is always
+ * present and `Diagnostic` itself has no defaults to strip — the static
+ * type matches the runtime shape exactly.
+ *
+ * ## Why this file lives at the package root, not `src/lib/`
+ *
+ * `svelte.config.js` aliases `'svelte-docinfo' → 'src/lib'` (load-bearing
+ * for fuz_ui's `library_gen`, a circular dev-dep). `@sveltejs/package`
+ * applies that alias to every file under `src/lib/`, including hand-written
+ * `.d.ts`, rewriting the `'svelte-docinfo/...'` imports below to relative
+ * paths. TypeScript doesn't resolve relative imports inside ambient
+ * `declare module` blocks in consumer projects — types silently collapse
+ * to `any`.
+ *
+ * Living at the root keeps the file out of `svelte-package`'s reach;
+ * `gro.config.ts` and `package.json` `files` re-register it for npm.
+ * Do not "fix" this by moving the file into `src/lib/`.
+ */
+declare module 'virtual:svelte-docinfo' {
+	import type {ModuleJsonInput} from 'svelte-docinfo/types.js';
+	import type {Diagnostic} from 'svelte-docinfo/diagnostics.js';
+	export const modules: Array<ModuleJsonInput>;
+	export const diagnostics: Array<Diagnostic>;
+	const data: {modules: Array<ModuleJsonInput>; diagnostics: Array<Diagnostic>};
+	export default data;
+}