@happyvertical/smrt-scanner 0.51.32 → 0.51.34

package/dist/scanner.d.ts

@@ -0,0 +1,266 @@
+/**
+ * OXC Scanner
+ *
+ * High-level scanner that orchestrates OXC parsing and inheritance resolution.
+ * Provides a simple API for scanning TypeScript files for SMRT classes.
+ */
+import type { ExternalManifest, OxcScannerOptions, ResolvedClassDefinition, ScanResults } from './types.js';
+/**
+ * Prunes that always apply, on top of whatever `exclude` a caller passes.
+ *
+ * `exclude` replaces {@link DEFAULT_EXCLUDE} wholesale, so every caller that
+ * narrowed the excludes also silently reopened `node_modules` — and installed
+ * dependencies are never a project's own `@smrt()` sources. Dot directories are
+ * generated or tool state (`.git`, `.svelte-kit`, `.turbo`, `.vercel`, agent
+ * scratch) and are pruned for the same reason: nothing authored lives there.
+ * `**\/.*` keeps hidden FILES out of the result too, so turning `dot` on to
+ * make these prunes work does not quietly widen what gets scanned.
+ *
+ * These are load-bearing for termination, not just for speed. See
+ * {@link OxcScanner.discoverFiles}.
+ */
+/**
+ * High-performance TypeScript scanner that discovers `@smrt()`-decorated
+ * classes in a project's source files.
+ *
+ * Orchestrates the two-phase scan pipeline:
+ * 1. **Phase 1 — Parse** (`scan()`): uses OXC (Rust) to parse TypeScript files
+ *    in parallel and extract raw class, field, method, and decorator metadata.
+ * 2. **Phase 2 — Resolve** (`resolve()`): walks inheritance chains, detects STI
+ *    hierarchies, and merges fields from ancestor classes.
+ *
+ * The common path is {@link scanAndResolve} which runs both phases in sequence.
+ *
+ * @example
+ * ```typescript
+ * import { OxcScanner } from '@happyvertical/smrt-scanner';
+ *
+ * const scanner = new OxcScanner({
+ *   cwd: process.cwd(),
+ *   include: ['src/**\/*.ts'],
+ *   exclude: ['**\/*.test.ts'],
+ * });
+ *
+ * const { results, resolved } = await scanner.scanAndResolve();
+ * console.log(`Found ${resolved.length} SMRT classes in ${results.fileCount} files`);
+ * ```
+ *
+ * @see {@link OxcScannerOptions} for all available configuration options.
+ * @see {@link scanDirectory} for a one-liner convenience wrapper.
+ */
+export declare class OxcScanner {
+    private options;
+    private resolver;
+    private scanResults;
+    /**
+     * Create a new `OxcScanner` with the given options.
+     *
+     * All options are optional. By default the scanner targets every `.ts` and
+     * `.tsx` file under `process.cwd()`, excluding `node_modules`, `dist`,
+     * `build`, declaration files, and test files.
+     *
+     * @param options - Scanner configuration. See {@link OxcScannerOptions}.
+     */
+    constructor(options?: OxcScannerOptions);
+    /**
+     * Phase 1 — Discover and parse TypeScript files using OXC.
+     *
+     * Uses `fast-glob` to enumerate matching files and then parses them in
+     * parallel with OXC (Rust).  The raw class definitions are registered with
+     * the internal {@link InheritanceResolver} for use in the subsequent
+     * {@link resolve} call.
+     *
+     * @returns A {@link ScanResults} object containing all classes found, any
+     *   parse errors, accumulated type aliases, SMRT import metadata, and
+     *   aggregate timing information.
+     *
+     * @example
+     * ```typescript
+     * const scanner = new OxcScanner({ cwd: '/project' });
+     * const results = await scanner.scan();
+     * console.log(`Parsed ${results.fileCount} files in ${results.totalParseTimeMs.toFixed(1)}ms`);
+     * ```
+     */
+    scan(): Promise<ScanResults>;
+    /**
+     * Phase 2 — Resolve inheritance chains for all scanned classes.
+     *
+     * Must be called after {@link scan}.  Walks each class's extends chain,
+     * detects STI hierarchies, merges ancestor fields for STI subclasses, and
+     * marks framework base classes.
+     *
+     * @returns An array of {@link ResolvedClassDefinition} objects — one for
+     *   every class that either carries `@smrt()` or extends a framework base
+     *   class (`SmrtObject`, `SmrtClass`, `SmrtCollection`).
+     *
+     * @throws {Error} If called before {@link scan}.
+     *
+     * @see {@link scanAndResolve} to run both phases in one call.
+     */
+    resolve(): ResolvedClassDefinition[];
+    /**
+     * Run both scan phases in a single call.
+     *
+     * Equivalent to calling `await scanner.scan()` followed by
+     * `scanner.resolve()`.  This is the most common entry point for callers
+     * that want the fully-resolved manifest-ready data in one step.
+     *
+     * @returns An object with:
+     *   - `results` — raw {@link ScanResults} from Phase 1.
+     *   - `resolved` — array of {@link ResolvedClassDefinition} from Phase 2.
+     *
+     * @example
+     * ```typescript
+     * const scanner = new OxcScanner({ cwd: '/project/src' });
+     * const { results, resolved } = await scanner.scanAndResolve();
+     * // resolved is ready to pass to ManifestAdapter.toManifest()
+     * ```
+     *
+     * @see {@link ManifestAdapter} to convert `resolved` into a manifest JSON.
+     */
+    scanAndResolve(): Promise<{
+        results: ScanResults;
+        resolved: ResolvedClassDefinition[];
+    }>;
+    /**
+     * Register an external package manifest for cross-package base class resolution.
+     *
+     * When a project class extends a class defined in an installed SMRT package,
+     * the resolver needs access to that package's class definitions to walk the
+     * full inheritance chain.  Call this method with each external package's
+     * {@link ExternalManifest} before calling {@link scan} or {@link resolve}.
+     *
+     * @param manifest - The external manifest to register, including `packageName`,
+     *   `packageVersion`, and a `classes` map keyed by class name.
+     *
+     * @see {@link ExternalManifest}
+     */
+    addExternalManifest(manifest: ExternalManifest): void;
+    /**
+     * Scan all discovered files for @happyvertical/smrt-* imports.
+     * Returns a map of package name → Set of imported class names.
+     *
+     * Used for tree-shaking: only external objects that are actually imported
+     * in the project's source files will be included in the manifest.
+     *
+     * Must be called after scan() or as part of scanAndResolve().
+     *
+     * @example
+     * ```typescript
+     * const scanner = new OxcScanner({ cwd: process.cwd() });
+     * await scanner.scan();
+     * const imports = scanner.scanSmrtImports();
+     * // Map { '@happyvertical/smrt-profiles' => Set { 'Person', 'Organization' } }
+     * ```
+     */
+    scanSmrtImports(): Map<string, Set<string>>;
+    /**
+     * Return aggregate statistics about the last scan.
+     *
+     * Can be called after {@link scan} has completed.  Returns counts useful for
+     * diagnostics and the `--stats` CLI flag.
+     *
+     * @returns An object with:
+     *   - `totalClasses` — total class declarations seen (including non-SMRT).
+     *   - `smrtClasses` — classes with `@smrt()` decorator.
+     *   - `stiClasses` — SMRT classes participating in an STI hierarchy.
+     *   - `maxInheritanceDepth` — length of the deepest inheritance chain.
+     *   - `fileCount` — number of files scanned.
+     *   - `parseTimeMs` — total wall-clock parse time in milliseconds.
+     */
+    getStats(): {
+        totalClasses: number;
+        smrtClasses: number;
+        stiClasses: number;
+        maxInheritanceDepth: number;
+        fileCount: number;
+        parseTimeMs: number;
+    };
+    /**
+     * Discover files to scan using fast-glob.
+     *
+     * Two settings here decide whether discovery terminates at all when the
+     * scanner is pointed at an application root rather than a package `src/`:
+     *
+     * - `dot: true`. Without it a `**` in an ignore pattern cannot cross a
+     *   dot segment, so `**\/node_modules/**` prunes `node_modules` at the root
+     *   but NOT `.svelte-kit/…/node_modules` or any other `node_modules` under a
+     *   dot directory. Those subtrees were then walked in full and every entry
+     *   discarded — unbounded work that could never produce a match.
+     * - `followSymbolicLinks: false`. pnpm materializes `node_modules` as a
+     *   symlink graph with cycles, so a link-following walk revisits the same
+     *   real directories once per path that reaches them.
+     *
+     * Together they were enough to exhaust a 4 GB heap on a consumer app that
+     * installs the published packages (#2275).
+     *
+     * Patterns are rewritten relative to `cwd` first. fast-glob matches `ignore`
+     * in whatever space the patterns use, so an absolute pattern would hand
+     * `**\/.*\/**` the project's own ancestors — a checkout under `~/.worktrees`
+     * or `~/.cache` would then match nothing at all, silently.
+     */
+    private discoverFiles;
+    /**
+     * Find declarations in files the CLASS scan did not cover.
+     *
+     * The class `include` is routinely narrowed to where models live, but an
+     * intent sidecar lives beside its component. Without this pass those
+     * declarations would be missing from every artifact with no diagnostic — a
+     * silent omission, and in the shipped SvelteKit template's own layout at
+     * that. Files already parsed by the class scan are skipped so a declaration
+     * is never counted twice and cannot collide with itself.
+     *
+     * @param alreadyScanned - Absolute paths the class scan already parsed.
+     */
+    private scanDeclarationsOutsideClassGlob;
+    /**
+     * Search `.svelte` files for declarations the scanner can never read.
+     *
+     * A `.svelte` file is not a TypeScript program and is never parsed here, so
+     * this pass produces diagnostics only — never an emitted entry. It exists
+     * because the alternative is silence: an intent declared inline in a
+     * component simply would not appear anywhere, with nothing to explain why.
+     */
+    private scanSvelteDeclarations;
+    /**
+     * Record a declaring module as a `cwd`-relative POSIX path.
+     *
+     * Emitted entries land in checked-in artifacts, so an absolute path would
+     * make them machine-specific and a Windows separator would make them
+     * platform-specific — either one churns a snapshot that is supposed to prove
+     * two builds agree.
+     */
+    private relativizeSourcePath;
+    /**
+     * Parse a single file with timing
+     */
+    private parseFileWithTiming;
+}
+/**
+ * Convenience wrapper that creates an {@link OxcScanner} for `dir` and runs
+ * both scan phases in a single call.
+ *
+ * @param dir - Directory to scan (resolved to an absolute path automatically).
+ * @param options - Scanner options, excluding `cwd` which is set from `dir`.
+ *   See {@link OxcScannerOptions}.
+ * @returns An object with `results` ({@link ScanResults}) and `resolved`
+ *   ({@link ResolvedClassDefinition}[]).
+ *
+ * @example
+ * ```typescript
+ * import { scanDirectory } from '@happyvertical/smrt-scanner';
+ *
+ * const { resolved } = await scanDirectory('src/', {
+ *   include: ['**\/*.ts'],
+ *   exclude: ['**\/*.test.ts'],
+ * });
+ * console.log(`Found ${resolved.length} SMRT classes`);
+ * ```
+ *
+ * @see {@link OxcScanner} for the full class API with more control.
+ */
+export declare function scanDirectory(dir: string, options?: Omit<OxcScannerOptions, 'cwd'>): Promise<{
+    results: ScanResults;
+    resolved: ResolvedClassDefinition[];
+}>;
+//# sourceMappingURL=scanner.d.ts.map

package/dist/scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../src/scanner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAaH,OAAO,KAAK,EAEV,gBAAgB,EAEhB,iBAAiB,EACjB,uBAAuB,EACvB,WAAW,EACZ,MAAM,YAAY,CAAC;AA2DpB;;;;;;;;;;;;;GAaG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,WAAW,CAA4B;IAE/C;;;;;;;;OAQG;gBACS,OAAO,GAAE,iBAAsB;IAwB3C;;;;;;;;;;;;;;;;;;OAkBG;IACG,IAAI,IAAI,OAAO,CAAC,WAAW,CAAC;IA8DlC;;;;;;;;;;;;;;OAcG;IACH,OAAO,IAAI,uBAAuB,EAAE;IAQpC;;;;;;;;;;;;;;;;;;;OAmBG;IACG,cAAc,IAAI,OAAO,CAAC;QAC9B,OAAO,EAAE,WAAW,CAAC;QACrB,QAAQ,EAAE,uBAAuB,EAAE,CAAC;KACrC,CAAC;IAOF;;;;;;;;;;;;OAYG;IACH,mBAAmB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAIrD;;;;;;;;;;;;;;;;OAgBG;IACH,eAAe,IAAI,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAwB3C;;;;;;;;;;;;;OAaG;IACH,QAAQ,IAAI;QACV,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;QACnB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;KACrB;IAUD;;;;;;;;;;;;;;;;;;;;;;OAsBG;YACW,aAAa;IAS3B;;;;;;;;;;;OAWG;YACW,gCAAgC;IAmC9C;;;;;;;OAOG;YACW,sBAAsB;IAoCpC;;;;;;;OAOG;IACH,OAAO,CAAC,oBAAoB;IAM5B;;OAEG;YACW,mBAAmB;CAIlC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,IAAI,CAAC,iBAAiB,EAAE,KAAK,CAAM,GAC3C,OAAO,CAAC;IACT,OAAO,EAAE,WAAW,CAAC;IACrB,QAAQ,EAAE,uBAAuB,EAAE,CAAC;CACrC,CAAC,CAOD"}

package/dist/source-location.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Source-offset helpers shared by the OXC class parser and the agent-surface
+ * matcher.
+ *
+ * Lives in its own module so `agent-surface.ts` can resolve a diagnostic's
+ * line/column without importing `oxc-parser.ts`, which imports it back.
+ */
+/**
+ * Extract line/column from offset in source text.
+ *
+ * Note: oxc-parser v0.108+ removed magicString, so this is computed manually.
+ *
+ * @param sourceText - Full source text the offset indexes into.
+ * @param offset - 0-based character offset.
+ * @returns 1-based line and column, or `undefined` when the offset is out of
+ *   range.
+ */
+export declare function getLineColumn(sourceText: string, offset: number): {
+    line: number;
+    column: number;
+} | undefined;
+//# sourceMappingURL=source-location.d.ts.map

package/dist/source-location.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-location.d.ts","sourceRoot":"","sources":["../src/source-location.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAmB9C"}