@happyvertical/smrt-scanner 0.30.0

package/dist/index.js

@@ -0,0 +1,163 @@
+import { O as OxcScanner, M as ManifestAdapter } from "./chunks/scanner-3K_xuVXN.js";
+import { I, e, p, a } from "./chunks/scanner-3K_xuVXN.js";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve, basename } from "node:path";
+const DEFAULT_INCLUDE = ["src/**/*.ts"];
+const DEFAULT_EXCLUDE = [
+  "**/*.test.ts",
+  "**/*.spec.ts",
+  "**/__tests__/**",
+  "**/*.svelte",
+  "**/node_modules/**",
+  "**/dist/**",
+  "**/*.d.ts"
+];
+const DEFAULT_SKIP_PACKAGES = [
+  "core",
+  "types",
+  "config",
+  "scanner",
+  "vitest",
+  "smrt-playground"
+];
+function resolveManifestPath(packageDir, pkgJson) {
+  const exportsMap = pkgJson.exports ?? {};
+  const entry = exportsMap["./manifest"] ?? exportsMap["./manifest.json"];
+  let relativeTarget;
+  if (typeof entry === "string") {
+    relativeTarget = entry;
+  } else if (entry && typeof entry === "object") {
+    const conditional = entry;
+    const candidate = conditional.default ?? conditional.import ?? conditional.types;
+    if (typeof candidate === "string") {
+      relativeTarget = candidate;
+    }
+  }
+  if (!relativeTarget) {
+    return null;
+  }
+  return resolve(packageDir, relativeTarget);
+}
+async function verifyManifestCompleteness(options) {
+  const packageDir = resolve(options.packageDir);
+  const include = options.include ?? DEFAULT_INCLUDE;
+  const exclude = options.exclude ?? DEFAULT_EXCLUDE;
+  const skipPackages = options.skipPackages ?? DEFAULT_SKIP_PACKAGES;
+  const packageJsonPath = resolve(packageDir, "package.json");
+  if (!existsSync(packageJsonPath)) {
+    return {
+      status: "skipped",
+      missing: [],
+      expectedCount: 0,
+      distCount: 0,
+      reason: `no package.json at ${packageDir}`
+    };
+  }
+  const pkgJson = JSON.parse(
+    readFileSync(packageJsonPath, "utf-8")
+  );
+  const packageName = pkgJson.name;
+  if (skipPackages.includes(basename(packageDir))) {
+    return {
+      status: "skipped",
+      packageName,
+      missing: [],
+      expectedCount: 0,
+      distCount: 0,
+      reason: "framework infrastructure package (does not use scanner manifest)"
+    };
+  }
+  const manifestPath = resolveManifestPath(packageDir, pkgJson);
+  if (!manifestPath) {
+    return {
+      status: "skipped",
+      packageName,
+      missing: [],
+      expectedCount: 0,
+      distCount: 0,
+      reason: "package does not publish a ./manifest export"
+    };
+  }
+  const scanner = new OxcScanner({ cwd: packageDir, include, exclude });
+  const { results, resolved } = await scanner.scanAndResolve();
+  const scanErrors = results.errors.filter((e2) => e2.severity === "error");
+  if (scanErrors.length > 0) {
+    const detail = scanErrors.map((e2) => {
+      const where = e2.line ? `${e2.filePath}:${e2.line}` : e2.filePath;
+      return `${where} — ${e2.message}`;
+    }).join("; ");
+    return {
+      status: "scan-error",
+      packageName,
+      manifestPath,
+      missing: [],
+      expectedCount: 0,
+      distCount: 0,
+      reason: `source scan reported ${scanErrors.length} parse error(s): ${detail}`
+    };
+  }
+  const adapter = new ManifestAdapter();
+  const expected = adapter.toManifest(resolved, {
+    packageName,
+    packageVersion: pkgJson.version,
+    typeAliases: results.typeAliases
+  });
+  const expectedKeys = Object.keys(expected.objects);
+  if (expectedKeys.length === 0) {
+    return {
+      status: "skipped",
+      packageName,
+      manifestPath,
+      missing: [],
+      expectedCount: 0,
+      distCount: 0,
+      reason: "no @smrt() objects found in source"
+    };
+  }
+  if (!existsSync(manifestPath)) {
+    return {
+      status: "missing-manifest",
+      packageName,
+      manifestPath,
+      missing: expectedKeys,
+      expectedCount: expectedKeys.length,
+      distCount: 0,
+      reason: `published manifest not found at ${manifestPath}`
+    };
+  }
+  let distObjects = {};
+  try {
+    const distManifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    distObjects = distManifest && typeof distManifest.objects === "object" ? distManifest.objects : {};
+  } catch (error) {
+    return {
+      status: "missing-manifest",
+      packageName,
+      manifestPath,
+      missing: expectedKeys,
+      expectedCount: expectedKeys.length,
+      distCount: 0,
+      reason: `published manifest is not valid JSON: ${error.message}`
+    };
+  }
+  const distKeys = new Set(Object.keys(distObjects));
+  const missing = expectedKeys.filter((key) => !distKeys.has(key));
+  return {
+    status: missing.length > 0 ? "incomplete" : "ok",
+    packageName,
+    manifestPath,
+    missing,
+    expectedCount: expectedKeys.length,
+    distCount: distKeys.size
+  };
+}
+export {
+  I as InheritanceResolver,
+  ManifestAdapter,
+  OxcScanner,
+  e as extractSmrtImports,
+  p as parseFile,
+  a as parseSource,
+  verifyManifestCompleteness
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/verify-completeness.ts"],"sourcesContent":["/**\n * Manifest completeness verification.\n *\n * Re-scans a package's `src/` with the same OXC scanner the build uses and\n * asserts that every `@smrt()`-decorated object (and its collection) is present\n * in the package's published `dist/manifest.json`. This is a publish-time guard:\n * downstream schema migration is manifest-driven, so a stale manifest that omits\n * an object means consumers can never create its table via `smrt db:migrate`.\n *\n * Root cause it guards against (issue #1483): `@happyvertical/smrt-jobs@0.27.41`\n * shipped a `dist/manifest.json` generated before `SmrtWorker` existed. The\n * source, exports, and `__smrt-register__` path were all correct, but the\n * published manifest had only 4 of 6 objects, so `_smrt_workers` was never\n * created and `TaskRunner.start()` threw on every consumer that upgraded.\n *\n * The check compares object-key SETS only. The downstream manifest-enrichment\n * passes (schema/validation/agent generation) mutate object entries but never\n * add or remove object keys, so the scanner + adapter object set is the source\n * of truth for \"which objects the published manifest must contain\". The\n * comparison is `expected ⊆ dist`: enrichment passes that add keys to `dist`\n * (e.g. STI children) never trigger a false failure.\n *\n * Parse errors are handled before the set comparison: a syntactically broken\n * source file drops its objects from `expected` AND `dist` symmetrically, which\n * a naive `expected ⊆ dist` would wave through as `ok`. The scan's\n * `severity:'error'` entries therefore short-circuit to a distinct `scan-error`\n * status so a broken source can never masquerade as a complete manifest.\n *\n * @see https://github.com/happyvertical/smrt/issues/1483\n */\n\nimport { existsSync, readFileSync } from 'node:fs';\nimport { basename, resolve } from 'node:path';\nimport { ManifestAdapter } from './manifest-adapter.js';\nimport { OxcScanner } from './scanner.js';\n\n/**\n * Source globs for the completeness scan. The build (`vite.config.base.ts`)\n * passes `include: ['src/**\\/*.ts']` and excludes `*.test.ts` / `*.spec.ts` (the\n * plugin also drops `*.svelte`); we reproduce that so the expected object set\n * matches what the build would publish. We additionally exclude\n * `**\\/__tests__\\/**` so any `@smrt()` fixtures in non-test helper modules under\n * `src/__tests__/` (e.g. `src/__tests__/helpers/*.ts`) are never required in the\n * published manifest. These extra exclusions can only shrink `expected` relative\n * to the build, so they can never cause a false failure — the check is\n * `expected ⊆ dist`.\n */\nconst DEFAULT_INCLUDE = ['src/**/*.ts'];\nconst DEFAULT_EXCLUDE = [\n  '**/*.test.ts',\n  '**/*.spec.ts',\n  '**/__tests__/**',\n  '**/*.svelte',\n  '**/node_modules/**',\n  '**/dist/**',\n  '**/*.d.ts',\n];\n\n/**\n * Framework-infrastructure packages whose published manifest is NOT produced by\n * the OXC scanner path (e.g. `@happyvertical/smrt-core` ships a curated static\n * manifest). Mirrors `skipSmrtPlugin` in `vite.config.base.ts`. Keyed by package\n * directory basename.\n */\nconst DEFAULT_SKIP_PACKAGES = [\n  'core',\n  'types',\n  'config',\n  'scanner',\n  'vitest',\n  'smrt-playground',\n];\n\nexport type VerifyManifestStatus =\n  | 'ok'\n  | 'incomplete'\n  | 'missing-manifest'\n  | 'scan-error'\n  | 'skipped';\n\nexport interface VerifyManifestCompletenessOptions {\n  /** Absolute or relative path to the package directory to verify. */\n  packageDir: string;\n  /** Source include globs (default mirrors the build). */\n  include?: string[];\n  /** Source exclude globs (default mirrors the build). */\n  exclude?: string[];\n  /** Package directory basenames to skip (default: framework infrastructure). */\n  skipPackages?: string[];\n}\n\nexport interface VerifyManifestCompletenessResult {\n  status: VerifyManifestStatus;\n  packageName?: string;\n  manifestPath?: string;\n  /** Qualified object keys present in source but missing from the manifest. */\n  missing: string[];\n  /** Number of objects the source is expected to contribute. */\n  expectedCount: number;\n  /** Number of objects present in the published manifest. */\n  distCount: number;\n  /** Human-readable explanation for `skipped` / `missing-manifest`. */\n  reason?: string;\n}\n\ninterface MinimalPackageJson {\n  name?: string;\n  version?: string;\n  exports?: Record<string, unknown>;\n}\n\n/**\n * Resolve the `./manifest` (or `./manifest.json`) export target to an absolute\n * path. Returns `null` when the package does not publish a manifest.\n */\nfunction resolveManifestPath(\n  packageDir: string,\n  pkgJson: MinimalPackageJson,\n): string | null {\n  const exportsMap = pkgJson.exports ?? {};\n  const entry = exportsMap['./manifest'] ?? exportsMap['./manifest.json'];\n\n  let relativeTarget: string | undefined;\n  if (typeof entry === 'string') {\n    relativeTarget = entry;\n  } else if (entry && typeof entry === 'object') {\n    const conditional = entry as Record<string, unknown>;\n    const candidate =\n      conditional.default ?? conditional.import ?? conditional.types;\n    if (typeof candidate === 'string') {\n      relativeTarget = candidate;\n    }\n  }\n\n  if (!relativeTarget) {\n    return null;\n  }\n\n  return resolve(packageDir, relativeTarget);\n}\n\n/**\n * Verify that `dist/manifest.json` contains every `@smrt()` object declared in\n * the package source. See module docs for the rationale and guarantees.\n */\nexport async function verifyManifestCompleteness(\n  options: VerifyManifestCompletenessOptions,\n): Promise<VerifyManifestCompletenessResult> {\n  const packageDir = resolve(options.packageDir);\n  const include = options.include ?? DEFAULT_INCLUDE;\n  const exclude = options.exclude ?? DEFAULT_EXCLUDE;\n  const skipPackages = options.skipPackages ?? DEFAULT_SKIP_PACKAGES;\n\n  const packageJsonPath = resolve(packageDir, 'package.json');\n  if (!existsSync(packageJsonPath)) {\n    return {\n      status: 'skipped',\n      missing: [],\n      expectedCount: 0,\n      distCount: 0,\n      reason: `no package.json at ${packageDir}`,\n    };\n  }\n\n  const pkgJson: MinimalPackageJson = JSON.parse(\n    readFileSync(packageJsonPath, 'utf-8'),\n  );\n  const packageName = pkgJson.name;\n\n  if (skipPackages.includes(basename(packageDir))) {\n    return {\n      status: 'skipped',\n      packageName,\n      missing: [],\n      expectedCount: 0,\n      distCount: 0,\n      reason:\n        'framework infrastructure package (does not use scanner manifest)',\n    };\n  }\n\n  const manifestPath = resolveManifestPath(packageDir, pkgJson);\n  if (!manifestPath) {\n    return {\n      status: 'skipped',\n      packageName,\n      missing: [],\n      expectedCount: 0,\n      distCount: 0,\n      reason: 'package does not publish a ./manifest export',\n    };\n  }\n\n  // Derive the object set the source SHOULD produce, using the same scanner and\n  // adapter the build uses (vite-plugin scanWithOxc).\n  const scanner = new OxcScanner({ cwd: packageDir, include, exclude });\n  const { results, resolved } = await scanner.scanAndResolve();\n\n  // A source file with a syntax error parses to `errors:[...], body:[]`, so any\n  // @smrt() class in it is dropped from BOTH the re-scanned `expected` set and\n  // (having never built) the published `dist`. Because the completeness check is\n  // `expected ⊆ dist`, the object vanishes symmetrically and the guard would\n  // return `ok` — silently defeating the #1483 guarantee for the exact case\n  // (broken source) that most needs catching. Surface scan errors as a distinct\n  // non-`ok` status instead of computing `expected` from a partial scan.\n  const scanErrors = results.errors.filter((e) => e.severity === 'error');\n  if (scanErrors.length > 0) {\n    const detail = scanErrors\n      .map((e) => {\n        const where = e.line ? `${e.filePath}:${e.line}` : e.filePath;\n        return `${where} — ${e.message}`;\n      })\n      .join('; ');\n    return {\n      status: 'scan-error',\n      packageName,\n      manifestPath,\n      missing: [],\n      expectedCount: 0,\n      distCount: 0,\n      reason: `source scan reported ${scanErrors.length} parse error(s): ${detail}`,\n    };\n  }\n\n  const adapter = new ManifestAdapter();\n  const expected = adapter.toManifest(resolved, {\n    packageName,\n    packageVersion: pkgJson.version,\n    typeAliases: results.typeAliases,\n  });\n  const expectedKeys = Object.keys(expected.objects);\n\n  // Nothing to verify if the package declares no SMRT objects (e.g. a package\n  // that publishes ./manifest but only ships base classes).\n  if (expectedKeys.length === 0) {\n    return {\n      status: 'skipped',\n      packageName,\n      manifestPath,\n      missing: [],\n      expectedCount: 0,\n      distCount: 0,\n      reason: 'no @smrt() objects found in source',\n    };\n  }\n\n  if (!existsSync(manifestPath)) {\n    return {\n      status: 'missing-manifest',\n      packageName,\n      manifestPath,\n      missing: expectedKeys,\n      expectedCount: expectedKeys.length,\n      distCount: 0,\n      reason: `published manifest not found at ${manifestPath}`,\n    };\n  }\n\n  let distObjects: Record<string, unknown> = {};\n  try {\n    const distManifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));\n    distObjects =\n      distManifest && typeof distManifest.objects === 'object'\n        ? distManifest.objects\n        : {};\n  } catch (error) {\n    return {\n      status: 'missing-manifest',\n      packageName,\n      manifestPath,\n      missing: expectedKeys,\n      expectedCount: expectedKeys.length,\n      distCount: 0,\n      reason: `published manifest is not valid JSON: ${(error as Error).message}`,\n    };\n  }\n\n  const distKeys = new Set(Object.keys(distObjects));\n  const missing = expectedKeys.filter((key) => !distKeys.has(key));\n\n  return {\n    status: missing.length > 0 ? 'incomplete' : 'ok',\n    packageName,\n    manifestPath,\n    missing,\n    expectedCount: expectedKeys.length,\n    distCount: distKeys.size,\n  };\n}\n"],"names":["e"],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,323 @@
+/**
+ * Describes a pre-loaded manifest from an installed SMRT package, used by
+ * {@link InheritanceResolver} to resolve base classes that originate outside
+ * the local project source.
+ *
+ * Build tooling (e.g. the SMRT CLI / vitest plugin) loads each installed
+ * `@happyvertical/smrt-*` package's `manifest.json` and converts it into an
+ * `ExternalManifest` before passing it to the scanner.
+ *
+ * @see {@link OxcScannerOptions.externalManifests}
+ * @see {@link InheritanceResolver.addExternalManifest}
+ */
+export declare interface ExternalManifest {
+    /** npm package name, e.g. `'@happyvertical/smrt-profiles'`. */
+    packageName: string;
+    /** SemVer version string of the installed package. */
+    packageVersion: string;
+    /** All class definitions exported by the package, keyed by class name. */
+    classes: Map<string, RawClassDefinition>;
+}
+
+/**
+ * Result produced by {@link ManifestAdapter.inferFieldType} for a single field.
+ *
+ * In addition to the inferred `type`, carries the `source` of the inference
+ * so callers can distinguish authoritative decorator-driven results from
+ * heuristic guesses and provide better diagnostics.
+ *
+ * @see {@link InferredFieldType} for valid `type` values.
+ * @see {@link ManifestAdapter.inferFieldType} for inference priority rules.
+ */
+export declare interface FieldTypeInference {
+    /** Inferred SMRT type */
+    type: InferredFieldType;
+    /** Related class for relationship types */
+    related?: string;
+    /** Default value if extractable */
+    defaultValue?: unknown;
+    /** Whether field is required */
+    required: boolean;
+    /** Inference source for debugging */
+    source: 'helper' | 'decorator' | 'annotation' | 'heuristic' | 'default';
+    /** Underlying type for meta fields (e.g., 'string' inside Meta<string>) */
+    underlyingType?: InferredFieldType;
+    /**
+     * Decorator-derived metadata that should be merged into the manifest
+     * field's `_meta` object. Used by `@crossPackageRef`, `@manyToMany`,
+     * `@meta` to carry options (`validate`, `through`, `indexed`, `idType`,
+     * etc.) that don't fit on the top-level FieldDefinition.
+     */
+    _meta?: Record<string, unknown>;
+}
+
+/**
+ * Result from scanning a single file
+ */
+export declare interface FileScanResult {
+    /** Source file path */
+    filePath: string;
+    /** Classes found in file */
+    classes: RawClassDefinition[];
+    /** Scan errors */
+    errors: ScanError[];
+    /** Parse time in milliseconds */
+    parseTimeMs: number;
+    /** Type alias declarations found in file (name → resolved type string) */
+    typeAliases: Record<string, string>;
+    /** SMRT package imports found in file (package name → Set of imported class names) */
+    smrtImports?: Map<string, Set<string>>;
+}
+
+/**
+ * The set of SMRT column types that the scanner can infer for a field.
+ *
+ * | Value | DB column type | Notes |
+ * |---|---|---|
+ * | `text` | `TEXT` / `VARCHAR` | Default for `string` and unknown types |
+ * | `integer` | `INTEGER` | `number` with `= 0` initialiser |
+ * | `decimal` | `DECIMAL` | `number` with `= 0.0` initialiser |
+ * | `boolean` | `BOOLEAN` | `boolean` annotation or literal initialiser |
+ * | `datetime` | `DATETIME` | `Date` annotation |
+ * | `json` | `JSON` / `TEXT` | Arrays, `Record<>`, object types |
+ * | `foreignKey` | `UUID` by default (FK column) | `@foreignKey(Class)` decorator |
+ * | `crossPackageRef` | `UUID` by default (no FK constraint) | `@crossPackageRef('@pkg:Class')` decorator |
+ * | `oneToMany` | — (virtual) | `@oneToMany(Class)` decorator |
+ * | `manyToMany` | — (virtual) | `@manyToMany(Class)` decorator |
+ * | `meta` | Stored in `_meta_data` | STI child field wrapped in `Meta<T>` |
+ * | `unknown` | — | Could not be determined |
+ *
+ * @see {@link FieldTypeInference} for the full inference result shape.
+ */
+export declare type InferredFieldType = 'text' | 'integer' | 'decimal' | 'boolean' | 'datetime' | 'json' | 'foreignKey' | 'crossPackageRef' | 'oneToMany' | 'manyToMany' | 'meta' | 'unknown';
+
+/**
+ * Configuration options for {@link OxcScanner}.
+ *
+ * All fields are optional; reasonable defaults are applied when omitted.
+ *
+ * @see {@link OxcScanner}
+ */
+export declare interface OxcScannerOptions {
+    /** Glob patterns to include */
+    include?: string[];
+    /** Glob patterns to exclude */
+    exclude?: string[];
+    /** Base directory for scanning */
+    cwd?: string;
+    /** Path to tsconfig.json for module resolution */
+    tsconfig?: string;
+    /** Whether to follow imports to find base classes */
+    followImports?: boolean;
+    /** Known base classes (avoid resolution) */
+    baseClasses?: string[];
+    /** Include private methods in output */
+    includePrivateMethods?: boolean;
+    /** Include static methods in output */
+    includeStaticMethods?: boolean;
+    /** External package manifests for base class resolution */
+    externalManifests?: Map<string, ExternalManifest>;
+}
+
+/**
+ * Type definitions for OXC-based SMRT scanner
+ *
+ * This module defines:
+ * 1. Raw types - Intermediate representation from OXC parsing (Phase 1)
+ * 2. Resolved types - After inheritance resolution (Phase 2)
+ * 3. Re-exports of smrt-core types for compatibility
+ */
+/**
+ * Raw class definition extracted from OXC AST
+ * Contains only syntactic information, no semantic resolution
+ */
+export declare interface RawClassDefinition {
+    /** Class name as declared in source */
+    className: string;
+    /** Absolute path to source file */
+    filePath: string;
+    /** Parent class name from extends clause (null if none) */
+    extendsClause: string | null;
+    /** Generic type argument from extends (e.g., "Meeting" from SmrtCollection<Meeting>) */
+    extendsTypeArg: string | null;
+    /** Parsed @smrt() decorator configuration object */
+    decoratorConfig: RawDecoratorConfig | null;
+    /** Has @smrt() decorator */
+    hasSmartDecorator: boolean;
+    /** Class properties/fields */
+    fields: RawFieldDefinition[];
+    /** Class methods */
+    methods: RawMethodDefinition[];
+    /** Start line in source file */
+    startLine: number;
+    /** End line in source file */
+    endLine: number;
+}
+
+/**
+ * Raw decorator information
+ */
+export declare interface RawDecorator {
+    /** Decorator name (e.g., "field", "foreignKey") */
+    name: string;
+    /** Raw arguments as strings */
+    arguments: string[];
+}
+
+/**
+ * Raw @smrt() decorator configuration
+ */
+export declare interface RawDecoratorConfig {
+    /** Table strategy: 'sti' | 'cti' */
+    tableStrategy?: 'sti' | 'cti';
+    /** Storage type for the generated id primary key */
+    idType?: 'uuid' | 'text';
+    /** Code-owned feature toggle declarations */
+    features?: Record<string, {
+        defaultEnabled: boolean;
+        label?: string;
+        description?: string;
+        metadata?: Record<string, unknown>;
+    }>;
+    /** API configuration */
+    api?: {
+        include?: string[];
+        exclude?: string[];
+    };
+    /** CLI configuration */
+    cli?: boolean | {
+        include?: string[];
+        exclude?: string[];
+        skipApiCheck?: boolean;
+        http?: boolean;
+    };
+    /** MCP configuration */
+    mcp?: {
+        include?: string[];
+        exclude?: string[];
+    };
+    /** Raw config object for unknown properties */
+    [key: string]: unknown;
+}
+
+/**
+ * Raw field definition from OXC AST
+ */
+export declare interface RawFieldDefinition {
+    /** Field name */
+    name: string;
+    /** TypeScript type annotation as string (e.g., "string", "number", "Date") */
+    typeAnnotation: string | null;
+    /** Raw initializer expression as string */
+    initializer: string | null;
+    /** For numeric literals: whether it contains a decimal point */
+    hasDecimalPoint: boolean;
+    /** For numeric literals: the actual numeric value */
+    numericValue: number | null;
+    /** Decorators applied to this field */
+    decorators: RawDecorator[];
+    /** Whether field is optional (has ?) */
+    optional: boolean;
+    /** Whether field is static */
+    isStatic: boolean;
+    /** Whether field is readonly */
+    readonly: boolean;
+    /** Whether field is private/protected */
+    accessibility: 'public' | 'private' | 'protected';
+    /** Start line in source */
+    line: number;
+}
+
+/**
+ * Raw method definition from OXC AST
+ */
+export declare interface RawMethodDefinition {
+    /** Method name */
+    name: string;
+    /** Whether method is async */
+    async: boolean;
+    /** Whether method is static */
+    isStatic: boolean;
+    /** Accessibility modifier */
+    accessibility: 'public' | 'private' | 'protected';
+    /** Method parameters */
+    parameters: RawParameterDefinition[];
+    /** Return type annotation as string */
+    returnType: string | null;
+    /** JSDoc description if present */
+    description: string | null;
+    /** Start line in source */
+    line: number;
+}
+
+/**
+ * Raw parameter definition
+ */
+export declare interface RawParameterDefinition {
+    /** Parameter name */
+    name: string;
+    /** Type annotation as string */
+    type: string | null;
+    /** Whether parameter is optional */
+    optional: boolean;
+    /** Default value as string */
+    defaultValue: string | null;
+}
+
+/**
+ * Resolved class definition with inheritance chain
+ */
+export declare interface ResolvedClassDefinition extends RawClassDefinition {
+    /** Full inheritance chain from base to this class */
+    inheritanceChain: string[];
+    /** STI base class name (if part of STI hierarchy) */
+    stiBase: string | null;
+    /** Effective table strategy (inherited or declared) */
+    effectiveTableStrategy: 'sti' | 'cti';
+    /** Whether this class uses STI (convenience boolean) */
+    isSTI: boolean;
+    /** Whether this class is a framework base class */
+    isFrameworkBase: boolean;
+    /** All fields including inherited (for STI) */
+    allFields: RawFieldDefinition[];
+    /** Package this class belongs to (if external) */
+    packageName: string | null;
+}
+
+/**
+ * Scan error
+ */
+export declare interface ScanError {
+    /** Error message */
+    message: string;
+    /** Source file */
+    filePath: string;
+    /** Line number (1-based) */
+    line?: number;
+    /** Column number (1-based) */
+    column?: number;
+    /** Error severity */
+    severity: 'error' | 'warning';
+}
+
+/**
+ * Result from scanning multiple files
+ */
+export declare interface ScanResults {
+    /** All scanned files */
+    files: FileScanResult[];
+    /** All classes found (flattened) */
+    classes: RawClassDefinition[];
+    /** All errors (flattened) */
+    errors: ScanError[];
+    /** Total parse time in milliseconds */
+    totalParseTimeMs: number;
+    /** Number of files scanned */
+    fileCount: number;
+    /** Accumulated type aliases across all files */
+    typeAliases: Record<string, string>;
+    /** Accumulated SMRT package imports across all files (package name → Set of imported class names) */
+    smrtImports?: Map<string, Set<string>>;
+}
+
+export { }

package/dist/types.js

@@ -0,0 +1,2 @@
+
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@happyvertical/smrt-scanner",
+  "version": "0.30.0",
+  "description": "High-performance TypeScript scanner using OXC for SMRT manifest generation",
+  "author": "HappyVertical",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "smrt-scan": "./bin/smrt-scan.js"
+  },
+  "files": [
+    "CLAUDE.md",
+    "bin",
+    "dist",
+    "AGENTS.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    }
+  },
+  "dependencies": {
+    "fast-glob": "3.3.3",
+    "minimatch": "10.1.1",
+    "oxc-parser": "^0.108.0",
+    "oxc-resolver": "^11.16.3"
+  },
+  "devDependencies": {
+    "@types/node": "25.0.9",
+    "tsx": "^4.21.0",
+    "vite": "7.3.1",
+    "vitest": "^4.0.17"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/happyvertical/smrt.git",
+    "directory": "packages/scanner"
+  },
+  "scripts": {
+    "build": "vite build",
+    "build:watch": "vite build --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "clean": "rm -rf dist"
+  }
+}