@dereekb/dbx-cli 13.38.0 → 13.40.0

package/model-test/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@dereekb/dbx-cli/model-test",
+  "version": "13.40.0",
+  "type": "module",
+  "sideEffects": false,
+  "peerDependencies": {
+    "@dereekb/util": "13.40.0",
+    "ts-morph": "^21.0.0"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.esm.js",
+      "default": "./index.esm.js"
+    }
+  },
+  "module": "./index.esm.js",
+  "main": "./index.esm.js",
+  "types": "./index.d.ts"
+}

package/model-test/src/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Public surface of `@dereekb/dbx-cli/model-test`.
+ *
+ * Pure, dependency-light scanners for an API app's test artifacts:
+ *
+ * - the `test/*` modules parse, search, and discover `*.spec.ts` files (the
+ *   `dbx_model_test_*` cluster), and
+ * - the `fixture/*` modules parse `src/test/fixture.ts` and scaffold fixture
+ *   triplets / forwarders (the extraction half of the `dbx_model_fixture_*`
+ *   cluster).
+ *
+ * Consumers (the `dbx-components-mcp` tool wrappers, the `dbx-components-cli`
+ * commands, and downstream scripts) layer disk I/O, argument parsing, and
+ * presentation around these functions.
+ *
+ * The fixture *validation* layer (`validateAppFixtures`, its diagnostic types,
+ * and the validation report formatters) lives in `@dereekb/dbx-components-mcp`
+ * because it depends on the rule-catalog remediation layer. The spec-file
+ * naming-convention helpers (`classifySpecFile`, `buildCanonicalFilename`,
+ * `recommendSpecPath`, `recommendBucketsForGroup`) live in `@dereekb/util` —
+ * import them from there.
+ */
+export { discoverSpecFilesByGroup, FUNCTION_DIR_REL, type DiscoveredSpecCatalog, type DiscoveredSpecFile, type DiscoveredSpecGroup } from './lib/test/discover.js';
+export { extractSpecTreeFromText, type ExtractSpecTreeInput } from './lib/test/extract.js';
+export { inspectSpecFile } from './lib/test/inspect.js';
+export { searchSpecTree } from './lib/test/search.js';
+export { findModelTestHotspots, type FindModelTestHotspotsConfig, type ModelTestHotspot, type ModelTestHotspotsResult, type SpecBucket } from './lib/test/hotspots.js';
+export { formatTreeAsJson, formatSearchAsJson } from './lib/test/format.json.js';
+export { formatTreeAsMarkdown, formatSearchAsMarkdown } from './lib/test/format.markdown.js';
+export { formatListAppAsJson, formatListAppAsMarkdown } from './lib/test/format.list-app.js';
+export { formatHotspotsAsJson, formatHotspotsAsMarkdown } from './lib/test/format.hotspots.js';
+export type { HelperDescribe, PrefixSource, SpecFileTree, SpecNode, SpecNodeKind, SpecSearchHit, SpecSearchQuery, SpecSearchResult, SpecTreeFilters, SpecTreeView } from './lib/test/types.js';
+export { classifyFixtureArchetype } from './lib/fixture/archetype.js';
+export { extractAppFixturesFromText, type ExtractAppFixturesInput } from './lib/fixture/extract.js';
+export { FIXTURE_RELATIVE_PATH, inspectAppFixtures } from './lib/fixture/inspect.js';
+export { formatListAsJson, formatLookupAsJson } from './lib/fixture/format.json.js';
+export { formatListAsMarkdown, formatLookupAsMarkdown } from './lib/fixture/format.markdown.js';
+export { renderFixtureScaffold, type RenderFixtureScaffoldInput, type RenderedFixtureScaffold, type RenderedInsertion, type ScaffoldParamsDependency } from './lib/fixture/scaffold.js';
+export { renderForwarders, type RenderForwardersInput, type RenderedForwarder, type RenderedForwarders } from './lib/fixture/forward.js';
+export type { AppFixturesExtraction, FactoryCall, FixtureArchetype, FixtureEntry, FixtureKind, FixtureMethod, FixtureParamsField, FixtureParamsType } from './lib/fixture/types.js';
+export { KNOWN_NON_MODEL_FIXTURE_FAMILIES, NON_MODEL_JSDOC_TAG, findFamilyByBaseClass, findFamilyByFactoryName, type FrameworkNonModelFixtureFamily } from './lib/fixture/framework-fixtures.js';

package/model-test/src/lib/fixture/archetype.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Pure archetype classifier for `modelTestContextFactory(...)` calls.
+ *
+ * Inputs come from the AST extractor — already-parsed factory call metadata
+ * and Params type fields. Output is one of the four archetypes used by the
+ * lookup, validate, and scaffold tools to speak the right dialect for each
+ * entry.
+ */
+import type { FactoryCall, FixtureArchetype, FixtureParamsType } from './types.js';
+/**
+ * Inputs accepted by `classifyFixtureArchetype()`.
+ */
+export interface ClassifyFixtureArchetypeInput {
+    readonly factory?: FactoryCall;
+    readonly params?: FixtureParamsType;
+}
+/**
+ * Classifies a fixture entry into one of the four archetypes.
+ *
+ * Sub-collection archetypes are detected by the factory's
+ * `getCollection(fi, params)` signature reading a parent fixture's document
+ * off `params`, OR by the presence of `collectionForDocument`. Top-level
+ * variants are split by whether the Params interface holds non-self fixture
+ * dependencies.
+ *
+ * Falls back to `top-level-simple` when the factory call is absent (e.g.
+ * the file declares a Fixture/Instance pair but registration was deleted)
+ * — the validator surfaces the missing factory separately.
+ *
+ * @param input - Parsed factory call + params metadata.
+ * @returns The archetype enum.
+ */
+export declare function classifyFixtureArchetype(input: ClassifyFixtureArchetypeInput): FixtureArchetype;

package/model-test/src/lib/fixture/extract.d.ts

@@ -0,0 +1,37 @@
+/**
+ * AST extractor for the `dbx_model_fixture_*` tool cluster.
+ *
+ * Parses an app's `src/test/fixture.ts` into the
+ * {@link AppFixturesExtraction} consumed by every tool in the cluster.
+ *
+ * Strategy:
+ * 1. Build a single ts-morph in-memory project containing only the fixture
+ *    file. Fixture files are workspace-local and self-contained for our
+ *    purposes — no symbol resolution beyond simple identifier lookup.
+ * 2. Detect the workspace `<Prefix>` from the base context fixture
+ *    (the class extending `FirebaseAdminNestTestContextFixture`).
+ * 3. Walk every class declaration, group `<Prefix><Model>TestContextFixture`
+ *    + `<Prefix><Model>TestContextInstance` pairs by model name, then
+ *    join in the matching `<Prefix><Model>TestContextParams` type and
+ *    `<prefix><Model>ContextFactory` / `<prefix><Model>Context` exports.
+ * 4. Classify each entry's archetype via {@link classifyFixtureArchetype}.
+ *
+ * The extractor accepts plain text input so specs can build fixtures
+ * directly without touching the filesystem.
+ */
+import type { AppFixturesExtraction } from './types.js';
+/**
+ * Inputs accepted by {@link extractAppFixturesFromText}.
+ */
+export interface ExtractAppFixturesInput {
+    readonly text: string;
+    readonly fixturePath: string;
+}
+/**
+ * Pure entry point used by inspect.ts and tests. Parses the supplied fixture
+ * text and returns the structured extraction; never touches disk.
+ *
+ * @param input - The raw fixture text + caller-relative path metadata.
+ * @returns The parsed extraction.
+ */
+export declare function extractAppFixturesFromText(input: ExtractAppFixturesInput): AppFixturesExtraction;

package/model-test/src/lib/fixture/format.json.d.ts

@@ -0,0 +1,24 @@
+/**
+ * JSON formatters for the `dbx_model_fixture_*` listing + lookup reports.
+ *
+ * Each renderer mirrors the markdown formatter's information density but
+ * emits a deterministic structured payload so downstream tooling can parse
+ * results without scraping markdown. The validation report's JSON formatter
+ * lives with the validator in `@dereekb/dbx-components-mcp`.
+ */
+import type { AppFixturesExtraction, FixtureEntry } from './types.js';
+/**
+ * Renders the listing report as JSON.
+ *
+ * @param extraction - The parsed fixture file.
+ * @returns The JSON body.
+ */
+export declare function formatListAsJson(extraction: AppFixturesExtraction): string;
+/**
+ * Renders the per-model lookup report as JSON.
+ *
+ * @param extraction - The parsed fixture file.
+ * @param entry - The matched entry.
+ * @returns The JSON body.
+ */
+export declare function formatLookupAsJson(extraction: AppFixturesExtraction, entry: FixtureEntry): string;

package/model-test/src/lib/fixture/format.markdown.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Markdown formatters for the `dbx_model_fixture_*` listing + lookup reports.
+ *
+ * Each tool emits its own report shape; this file groups the renderers so
+ * the per-tool wrappers stay thin. The validation report's markdown formatter
+ * lives with the validator in `@dereekb/dbx-components-mcp`.
+ */
+import type { AppFixturesExtraction, FixtureEntry } from './types.js';
+/**
+ * Renders the listing report for `dbx_model_fixture_list_app`.
+ *
+ * @param extraction - The parsed fixture file.
+ * @returns The markdown body.
+ */
+export declare function formatListAsMarkdown(extraction: AppFixturesExtraction): string;
+/**
+ * Renders the per-model lookup report for `dbx_model_fixture_lookup`.
+ *
+ * @param extraction - The parsed fixture file.
+ * @param entry - The matched entry.
+ * @returns The markdown body.
+ */
+export declare function formatLookupAsMarkdown(extraction: AppFixturesExtraction, entry: FixtureEntry): string;

package/model-test/src/lib/fixture/forward.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Forwarder generator for `dbx_model_fixture_forward`.
+ *
+ * Pure text generation — given a parsed entry, returns the source of every
+ * forwarder method that should be inserted into the Fixture class. Disk
+ * mutation is handled by the tool wrapper.
+ */
+import type { FixtureEntry } from './types.js';
+/**
+ * One forwarder method to insert into the Fixture class.
+ */
+export interface RenderedForwarder {
+    readonly method: string;
+    readonly source: string;
+}
+/**
+ * Inputs accepted by {@link renderForwarders}.
+ */
+export interface RenderForwardersInput {
+    readonly entry: FixtureEntry;
+    readonly methods?: readonly string[];
+}
+/**
+ * Result of {@link renderForwarders}.
+ */
+export interface RenderedForwarders {
+    readonly added: readonly RenderedForwarder[];
+    readonly skippedAlreadyForwarded: readonly string[];
+    readonly missingFromInstance: readonly string[];
+}
+/**
+ * Returns the forwarder source for every public Instance method that
+ * doesn't yet have a Fixture counterpart.
+ *
+ * The forwarder body is a thin wrapper:
+ * ```
+ * async <name>(<paramText>): <returnType> {
+ *   return this.instance.<name>(<args>);
+ * }
+ * ```
+ *
+ * Existing Fixture methods with the same name are left alone; they're
+ * reported in `skippedAlreadyForwarded`.
+ *
+ * @param input - The entry to forward + optional whitelist of method names.
+ * @returns The rendered forwarders + skip metadata.
+ */
+export declare function renderForwarders(input: RenderForwardersInput): RenderedForwarders;

package/model-test/src/lib/fixture/framework-fixtures.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Catalog of framework-provided fixture families that produce
+ * `<…>TestContextFixture` / `<…>TestContextInstance` class pairs but are NOT
+ * backed by a Firestore model.
+ *
+ * The fixture validator and lookup/list formatters consult this list to
+ * recognize the pattern automatically — downstream apps that subclass these
+ * bases (or register via the listed factory) get accurate classification and
+ * skip the `triplet-incomplete` / model-registry diagnostics that otherwise
+ * fire on every Fixture/Instance pair.
+ *
+ * Add a new entry here whenever the framework introduces another non-model
+ * fixture family. Both the inheritance signal (`baseFixtureClass` /
+ * `baseInstanceClass`) and the factory-call signal (`factoryName`) are
+ * supported; either alone is sufficient.
+ */
+export interface FrameworkNonModelFixtureFamily {
+    /**
+     * Discriminator written to {@link FixtureEntry.kind} when the family
+     * matches.
+     */
+    readonly kind: 'authorized-user';
+    /**
+     * Variable name of the framework factory used to register the pair, e.g.
+     * `authorizedUserContextFactory`. Matched against the call expression
+     * inside the entry's factory body.
+     */
+    readonly factoryName: string;
+    /**
+     * Class name of the framework-provided Fixture base that downstream
+     * subclasses extend.
+     */
+    readonly baseFixtureClass: string;
+    /**
+     * Class name of the framework-provided Instance base that downstream
+     * subclasses extend.
+     */
+    readonly baseInstanceClass: string;
+    /**
+     * Module path the bases and factory are exported from. Surfaced in
+     * lookup/list output so consumers know where to import from.
+     */
+    readonly module: string;
+    /**
+     * One-line human description rendered in the fixture lookup/list output.
+     */
+    readonly description: string;
+}
+export declare const KNOWN_NON_MODEL_FIXTURE_FAMILIES: readonly FrameworkNonModelFixtureFamily[];
+/**
+ * JSDoc tag the extractor honors to mark a Fixture/Instance pair as
+ * intentionally non-model. Either Fixture or Instance class can carry the
+ * tag; presence on either is sufficient.
+ */
+export declare const NON_MODEL_JSDOC_TAG = "dbxFixtureNotModel";
+/**
+ * Looks up a framework family by factory call name.
+ *
+ * @param factoryCallName - The identifier name appearing in the factory body
+ *   call expression (e.g. `authorizedUserContextFactory`)
+ * @returns The matched family, or `undefined`
+ */
+export declare function findFamilyByFactoryName(factoryCallName: string): FrameworkNonModelFixtureFamily | undefined;
+/**
+ * Looks up a framework family by Fixture or Instance base class name.
+ *
+ * @param baseClassName - The class identifier on the `extends` clause.
+ * @returns The matched family, or `undefined`
+ */
+export declare function findFamilyByBaseClass(baseClassName: string): FrameworkNonModelFixtureFamily | undefined;

package/model-test/src/lib/fixture/inspect.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Filesystem inspection for the `dbx_model_fixture_*` cluster.
+ *
+ * Reads `<apiDir>/src/test/fixture.ts` from disk and feeds the text through
+ * `extractAppFixtures()`. Centralising the I/O keeps the pure layers free of
+ * file-system concerns; specs build extractions directly without touching
+ * the disk.
+ */
+import type { AppFixturesExtraction } from './types.js';
+/**
+ * Conventional location of the test fixture file inside an API app.
+ */
+export declare const FIXTURE_RELATIVE_PATH = "src/test/fixture.ts";
+/**
+ * Reads `<apiDir>/src/test/fixture.ts` and returns the parsed extraction.
+ *
+ * @param apiAbs - Absolute path to the API app root.
+ * @param apiRel - Caller-supplied relative path (used for messages and
+ *   path metadata; unused for I/O)
+ * @returns The parsed extraction.
+ */
+export declare function inspectAppFixtures(apiAbs: string, apiRel: string): Promise<AppFixturesExtraction>;

package/model-test/src/lib/fixture/scaffold.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Scaffold renderer for `dbx_model_fixture_scaffold`.
+ *
+ * Pure text generation — given a parsed extraction and an archetype-aware
+ * scaffold spec, produces the snippet that the tool wrapper appends to
+ * `fixture.ts`. Direct disk mutation lives in the tool wrapper; this module
+ * stays testable without touching the filesystem.
+ *
+ * Each archetype owns a templated factory call; the Params interface,
+ * Instance class, and Fixture class are shared shapes.
+ */
+import type { AppFixturesExtraction, FixtureArchetype } from './types.js';
+/**
+ * One fixture dependency declared on the new Params interface.
+ *
+ * `field` is the param field name (e.g. `'sg'`); `fixtureModel` is the
+ * bare model name of the parent fixture (e.g. `'SchoolGroup'`). `optional`
+ * and `array` toggle the field's modality.
+ */
+export interface ScaffoldParamsDependency {
+    readonly field: string;
+    readonly fixtureModel: string;
+    readonly optional?: boolean;
+    readonly array?: boolean;
+}
+/**
+ * Inputs accepted by {@link renderFixtureScaffold}.
+ */
+export interface RenderFixtureScaffoldInput {
+    readonly model: string;
+    readonly prefix: string;
+    readonly archetype: FixtureArchetype;
+    readonly parentFixture?: string;
+    readonly parentFixtureField?: string;
+    readonly paramsDependsOn?: readonly ScaffoldParamsDependency[];
+    readonly withInitDocument?: boolean;
+    readonly collectionGenericArg?: string;
+    readonly modelDocumentTypeName?: string;
+    readonly factoryNamePrefix?: string;
+}
+/**
+ * Output of {@link renderFixtureScaffold}.
+ */
+export interface RenderedFixtureScaffold {
+    readonly snippet: string;
+    readonly todos: readonly string[];
+    readonly inserted: readonly RenderedInsertion[];
+    readonly paramsTypeName: string;
+    readonly fixtureClassName: string;
+    readonly instanceClassName: string;
+    readonly factoryName: string;
+    readonly singletonName: string;
+}
+/**
+ * One emitted code block reported back to the caller for follow-up edits.
+ */
+export interface RenderedInsertion {
+    readonly kind: 'params' | 'instance' | 'fixture' | 'factory' | 'singleton';
+    readonly name: string;
+}
+/**
+ * Builds the scaffold snippet for a new fixture triplet.
+ *
+ * The snippet is appended to `fixture.ts` as one block (with a leading
+ * `// MARK:` divider) so all five entities — Params, Instance, Fixture,
+ * Factory, Singleton — land in one logical section. The disk-mutation tool
+ * wrapper inserts this string at the end of the file.
+ *
+ * @param extraction - The current parse of `fixture.ts` (used only to
+ *   detect import collisions and pick context fixture/instance names)
+ * @param input - Scaffold spec.
+ * @returns The rendered snippet plus a placeholder checklist.
+ */
+export declare function renderFixtureScaffold(extraction: AppFixturesExtraction, input: RenderFixtureScaffoldInput): RenderedFixtureScaffold;

package/model-test/src/lib/fixture/types.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Extraction types shared by the `dbx_model_fixture_*` tool cluster.
+ *
+ * The cluster reads an app's `<root>/src/test/fixture.ts`, identifies every
+ * `<Prefix><Model>TestContext{Fixture,Instance,Params}` triplet plus its
+ * `modelTestContextFactory(...)` call, and returns information used by the
+ * lookup, list, validate, scaffold, and forward tools.
+ *
+ * The classifier (see `archetype.ts`) sorts each entry into one of four
+ * archetypes. The validator and scaffold tools speak the dialect of the
+ * archetype so 8-generic sub-collection factories aren't conflated with the
+ * 7-generic top-level shape.
+ *
+ * The validation diagnostic types (`FixtureDiagnostic`, `FixtureValidationResult`,
+ * the diagnostic-code union, and the model registry) live alongside the
+ * `validateAppFixtures` implementation in `@dereekb/dbx-components-mcp`, since
+ * they depend on the rule-catalog remediation layer.
+ */
+/**
+ * Configuration archetypes for `modelTestContextFactory(...)` calls.
+ *
+ * - `top-level-simple` — 7 generics, `getCollection(fi)` is single-arg, no
+ *   parent-fixture dependency on `Params`.
+ * - `top-level-with-deps` — top-level model whose `Params` interface adds
+ *   sibling fixture refs (e.g. an authorized user). `getCollection` remains
+ *   single-arg.
+ * - `sub-collection` — 8 generics with the explicit `FirestoreCollection`
+ *   generic; `getCollection(fi, params)` reads a parent fixture's document
+ *   off `params`.
+ * - `sub-collection-traversal` — sub-collection variant that also wires
+ *   `collectionForDocument` so the framework can traverse a child document
+ *   back to its parent collection.
+ */
+export type FixtureArchetype = 'top-level-simple' | 'top-level-with-deps' | 'sub-collection' | 'sub-collection-traversal';
+/**
+ * Classification of a Fixture/Instance pair by what it represents.
+ *
+ * - `firestore-model` — the default; the pair is registered via
+ *   `modelTestContextFactory(...)` and corresponds to a Firestore document
+ *   model. All validator rules apply.
+ * - `authorized-user` — the pair is part of the framework's `AuthorizedUser`
+ *   family (extends `AuthorizedUserTestContextFixture`/`Instance` or is
+ *   registered via `authorizedUserContextFactory`). Model-specific rules
+ *   (`triplet-incomplete`, `archetype-inconsistent`, etc.) are skipped.
+ * - `non-model` — the pair is explicitly opted out of model validation via
+ *   the `@dbxFixtureNotModel` JSDoc tag on the Fixture or Instance class.
+ *   Same rule gating as `authorized-user`.
+ */
+export type FixtureKind = 'firestore-model' | 'authorized-user' | 'non-model';
+/**
+ * One method declared on an Instance or Fixture class. `signature` is the raw
+ * parameter list copied verbatim from ts-morph (including parameter types and
+ * default values) so the forward tool can reproduce it without rewriting type
+ * text.
+ */
+export interface FixtureMethod {
+    readonly name: string;
+    readonly isStatic: boolean;
+    readonly isAsync: boolean;
+    readonly visibility: 'public' | 'private' | 'protected';
+    readonly parameterText: string;
+    readonly returnTypeText?: string;
+    readonly line: number;
+    readonly endLine: number;
+}
+/**
+ * One field on a `<Prefix><Model>TestContextParams` interface.
+ *
+ * `fixtureModel` is set when the field's type resolves to a sibling
+ * `<Prefix><Model>TestContextFixture`. The pair `{ field, fixtureModel }`
+ * forms a dependency edge consumed by the validator's parent-fixture-naming
+ * rule.
+ */
+export interface FixtureParamsField {
+    readonly name: string;
+    readonly typeText: string;
+    readonly optional: boolean;
+    readonly fixtureModel?: string;
+    readonly array?: boolean;
+}
+/**
+ * Parsed metadata for a `<Prefix><Model>TestContextParams` interface or type
+ * alias.
+ *
+ * `extendsPartial` is `true` when the interface extends `Partial<Model>` (the
+ * common case for top-level models). `aliasOfPartial` is `true` for the
+ * `type Foo = Partial<Bar>` alias pattern used by simple guestbook-style
+ * params. Standalone interfaces with no `extends` clause set both to `false`
+ * — typical for sub-collection params that don't carry the model's own
+ * fields.
+ */
+export interface FixtureParamsType {
+    readonly name: string;
+    readonly kind: 'interface' | 'alias';
+    readonly extendsPartial: boolean;
+    readonly aliasOfPartial: boolean;
+    readonly modelName?: string;
+    readonly fields: readonly FixtureParamsField[];
+    readonly line: number;
+}
+/**
+ * The two-arg metadata for the `modelTestContextFactory<...>(...)` call.
+ *
+ * The validator compares `genericArgs[0]`/`genericArgs[1]` (model + document
+ * type) against the Fixture/Instance class generic args; the scaffold tool
+ * reproduces the same generic count when adding new entries.
+ */
+export interface FactoryCall {
+    readonly factoryName: string;
+    readonly singletonName?: string;
+    readonly genericArgs: readonly string[];
+    readonly hasParamsGetCollection: boolean;
+    readonly hasCollectionForDocument: boolean;
+    readonly hasInitDocument: boolean;
+    readonly parentFixtureFieldFromGetCollection?: string;
+    readonly line: number;
+}
+/**
+ * One `<Prefix><Model>TestContext{Fixture,Instance,Params}` triplet.
+ *
+ * The triplet is keyed by `model` (the bare model name with the workspace
+ * prefix stripped). All five anchors must be present for the validator to
+ * treat the triplet as complete.
+ */
+export interface FixtureEntry {
+    readonly model: string;
+    readonly prefix: string;
+    readonly archetype: FixtureArchetype;
+    /**
+     * Classification of what the Fixture/Instance pair represents. Defaults to
+     * `firestore-model`; framework-provided non-model families and pairs
+     * tagged with `@dbxFixtureNotModel` opt out of model-specific validator
+     * rules.
+     */
+    readonly kind: FixtureKind;
+    /**
+     * When `kind !== 'firestore-model'`, identifies the framework family that
+     * matched (e.g. `'authorized-user'`) so lookup/list output can describe
+     * the pair. Set together with `kind`.
+     */
+    readonly nonModelFamily?: 'authorized-user' | 'jsdoc-tag';
+    readonly fixtureClassName: string;
+    readonly instanceClassName: string;
+    readonly paramsTypeName: string;
+    readonly factoryName?: string;
+    readonly singletonName?: string;
+    readonly fixtureExtendsGenerics: readonly string[];
+    readonly instanceExtendsGenerics: readonly string[];
+    readonly fixtureMethods: readonly FixtureMethod[];
+    readonly instanceMethods: readonly FixtureMethod[];
+    readonly params?: FixtureParamsType;
+    readonly factory?: FactoryCall;
+    readonly fixtureLine: number;
+    readonly fixtureEndLine: number;
+    readonly instanceLine: number;
+    readonly instanceEndLine: number;
+}
+/**
+ * Aggregate result returned by `extractAppFixtures()`.
+ *
+ * `prefix` is detected from the `<Prefix>ContextFixture` class in the file —
+ * scaffolding and validation derive everything from this single anchor so no
+ * tool hard-codes `DemoApi` or `HellosubsApi`.
+ *
+ * `unrecognizedClassNames` collects classes that match the
+ * `*TestContextFixture` / `*TestContextInstance` suffix but couldn't be
+ * paired into a triplet, so the validator can flag orphans.
+ */
+export interface AppFixturesExtraction {
+    readonly fixturePath: string;
+    readonly prefix?: string;
+    readonly entries: readonly FixtureEntry[];
+    readonly unrecognizedClassNames: readonly string[];
+    readonly identityImports: readonly string[];
+}

package/model-test/src/lib/test/discover.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Spec-file discovery for the `dbx_model_test_list_app` tool.
+ *
+ * Walks `<apiDir>/src/app/function/` and returns every `*.spec.ts` file
+ * grouped by its parent folder, with each file pre-classified via
+ * {@link classifySpecFile} so the wrapper can render listings and drift
+ * reports without re-parsing filenames.
+ *
+ * The walker is shallow (one level deep — exactly the model-group folders),
+ * matching the convention used across hellosubs / demo-api. Files nested
+ * deeper are still picked up but reported under their immediate parent
+ * folder so the classifier's group-vs-folder check stays meaningful.
+ */
+import { type SpecFileClassification } from '@dereekb/util';
+/**
+ * Conventional subdirectory under an API app that houses model-group tests.
+ */
+export declare const FUNCTION_DIR_REL = "src/app/function";
+/**
+ * One discovered model group with its spec files (classified).
+ */
+export interface DiscoveredSpecGroup {
+    readonly group: string;
+    /**
+     * Caller-relative path to the group folder (e.g.
+     * `apps/hellosubs-api/src/app/function/job`).
+     */
+    readonly folderRel: string;
+    readonly files: readonly DiscoveredSpecFile[];
+}
+/**
+ * One discovered spec file with its classification + caller-relative path.
+ */
+export interface DiscoveredSpecFile {
+    readonly filename: string;
+    /**
+     * Caller-relative path to the file (e.g.
+     * `apps/hellosubs-api/src/app/function/job/job.crud.spec.ts`).
+     */
+    readonly fileRel: string;
+    readonly classification: SpecFileClassification;
+}
+/**
+ * Aggregate result of {@link discoverSpecFilesByGroup}.
+ */
+export interface DiscoveredSpecCatalog {
+    /**
+     * Caller-relative path to the API app (echoed for the formatter).
+     */
+    readonly apiRel: string;
+    /**
+     * Caller-relative path to the function-tests root (e.g.
+     * `apps/hellosubs-api/src/app/function`).
+     */
+    readonly functionDirRel: string;
+    readonly groups: readonly DiscoveredSpecGroup[];
+    /**
+     * Total `.spec.ts` files discovered across all groups (canonical + drift).
+     */
+    readonly totalSpecFiles: number;
+    /**
+     * Total drift entries — i.e. classifications with `isCanonical === false`
+     * that are not `non-spec` / `non-group`.
+     */
+    readonly totalDriftFiles: number;
+}
+/**
+ * Walks `<apiAbs>/src/app/function/` and returns the grouped, classified
+ * catalog. Folders with no `.spec.ts` files are omitted. Files in the
+ * function root that don't live under a group folder are also omitted (the
+ * convention is one group folder per top-level entry).
+ *
+ * @param config - Inputs.
+ * @param config.apiAbs - Absolute path to the API app root.
+ * @param config.apiRel - Caller-relative API-app path (used for output paths).
+ * @returns The discovered catalog.
+ */
+export declare function discoverSpecFilesByGroup(config: {
+    readonly apiAbs: string;
+    readonly apiRel: string;
+}): Promise<DiscoveredSpecCatalog>;