rastack 0.0.22 → 0.0.23

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.0.23](https://github.com/theserverkid/reactapistack/compare/v0.0.22...v0.0.23) (2026-07-09)
+
 ### [0.0.22](https://github.com/theserverkid/reactapistack/compare/v0.0.21...v0.0.22) (2026-07-09)
 
 ### [0.0.21](https://github.com/theserverkid/reactapistack/compare/v0.0.20...v0.0.21) (2026-07-08)

package/cache/cache.ts

@@ -11,7 +11,7 @@
  *   written they never change — so a cached copy is correct forever
  *   (cache-first; the network is only touched for files never seen before).
  *
- * Seeding hands the cached bytes to the WASM engine (`RadApi.seedFile`), which
+ * Seeding hands the cached bytes to the WASM engine (`RastackApi.seedFile`), which
  * reads the *actual* Parquet/metadata files — the cache is a transparent layer
  * between object storage and the engine, not a new store format.
  *

package/cache/revocation.ts

@@ -31,7 +31,7 @@ export interface PurgeLocalDataOptions {
   cacheStorage?: CacheStorage;
   /**
    * IndexedDB databases to delete outright — the persisted warehouse snapshot
-   * (`rad-warehouse…`) and the sync-engine store, which hold row data derived
+   * (`rastack-warehouse…`) and the sync-engine store, which hold row data derived
    * from the revoked access.
    */
   databases?: string[];

package/cache/storage.ts

@@ -33,7 +33,7 @@ function openDb(name: string): Promise<any> {
 export class IndexedDbCacheStorage implements CacheStorage {
   private db: Promise<any>;
 
-  constructor(databaseName = "rad-iceberg-cache") {
+  constructor(databaseName = "rastack-iceberg-cache") {
     this.db = openDb(databaseName);
   }
 

package/cache/types.ts

@@ -36,7 +36,7 @@ export interface WarehouseFileSource {
   fetchFile(key: string): Promise<Uint8Array | null>;
 }
 
-/** The engine surface seeding needs (the WASM `RadApi`). */
+/** The engine surface seeding needs (the WASM `RastackApi`). */
 export interface SeedableEngine {
   seedFile(key: string, bytes: Uint8Array): Promise<void>;
 }

package/define.ts

@@ -0,0 +1,2 @@
+/** `rastack/define` — the resource() authoring DSL. */
+export * from "./src/define";

package/dist/compile/analyze.js

@@ -117,7 +117,7 @@ function analyzeField(name, initializer, checker) {
     const fieldType = checker.getTypeAtLocation(initializer);
     // Foreign key: the field type is Ref<App, Model>. Recover the target from
     // the string-literal type arguments — this is the "infer FK from types" step.
-    if (fieldType.getProperty("__radRef")) {
+    if (fieldType.getProperty("__rastackRef")) {
         const app = literalTypeProp(fieldType, "__app", checker, initializer);
         const model = literalTypeProp(fieldType, "__model", checker, initializer);
         if (app && model) {
@@ -125,8 +125,8 @@ function analyzeField(name, initializer, checker) {
         }
         return undefined;
     }
-    // Scalar: the field type carries a `__radScalar` string-literal discriminant.
-    const scalar = literalTypeProp(fieldType, "__radScalar", checker, initializer);
+    // Scalar: the field type carries a `__rastackScalar` string-literal discriminant.
+    const scalar = literalTypeProp(fieldType, "__rastackScalar", checker, initializer);
     if (!scalar)
         return undefined;
     const field = { name, type: scalar };

package/dist/compile/entities.d.ts

@@ -0,0 +1,68 @@
+import * as ts from "typescript";
+import { ResourceModel } from "./model";
+/**
+ * Interface-driven resource inference — "the entities in the app are a list of
+ * interfaces".
+ *
+ * Instead of (or alongside) the `resource()` DSL, an app can describe its data
+ * as plain TypeScript interfaces and consume them through typed hooks. The
+ * analyser works the resource graph out from the *usage*:
+ *
+ * 1. **Roots come from the hooks.** Every hook call that carries a type
+ *    argument — `useEntityList<Airport>(…)`, `useQuery<Terminal>(…)` — marks
+ *    the interface behind that type argument as an entity. An interface can
+ *    also opt in explicitly with a `@rastackResource` JSDoc tag.
+ * 2. **Datatypes come from the interfaces.** Each property's TypeScript type
+ *    maps to a manifest scalar (`string` → string, `number` → float,
+ *    `boolean` → bool, `Date` → datetime). Constraints are carried in the
+ *    type system with `DbConfig` brands from `rastack/types` —
+ *    `code: string & Unique & MaxLength<3>`, `age: Int` — or, equivalently,
+ *    as JSDoc tags (`@unique`, `@maxLength 3`, `@int`, `@uuid`, `@default`).
+ *    Optional / `| null` properties become nullable fields.
+ * 3. **Foreign keys come from the type system.** A property whose type is
+ *    another entity interface is a foreign key, and the referenced interface
+ *    is pulled into the resource graph transitively — the closure of the
+ *    hook-rooted interfaces is the app's resource set.
+ * 4. **Circular dependencies are detected.** The FK graph is walked for
+ *    cycles; a cycle is an *error* when every edge in it is required (no row
+ *    could ever be inserted) and a *warning* when it is breakable through a
+ *    nullable field (e.g. an optional self-referencing `manager`).
+ *
+ * ```ts
+ * // entities/airports.ts
+ * export interface Airport {
+ *   code: string;   // JSDoc tags refine: @maxLength 3, @unique
+ *   name: string;
+ * }
+ * export interface Terminal {
+ *   airport: Airport;   // FK — inferred from the property type
+ *   label: string;
+ * }
+ *
+ * // app/screen.tsx — the hook call is what roots the graph
+ * const terminals = useEntityList<Terminal>("terminals");
+ * // → resources: airports.terminal (root) + airports.airport (transitive)
+ * ```
+ *
+ * Naming: `model` is the lower-camel interface name (a leading `I` prefix as
+ * in generated `IFlight` interfaces is stripped, so hook usage of generated
+ * types round-trips onto the same resource); `app` defaults to the defining
+ * file's basename. Both are overridable with `@rastackApp` / `@rastackModel` tags.
+ */
+export interface EntityDiagnostic {
+    severity: "error" | "warning";
+    message: string;
+}
+export interface EntityAnalysis {
+    resources: ResourceModel[];
+    diagnostics: EntityDiagnostic[];
+}
+export declare function analyzeEntities(program: ts.Program, fileNames: string[]): EntityAnalysis;
+/**
+ * Detect cycles in the FK graph. Works on the *merged* resource set, so cycles
+ * authored through the `resource()` DSL are caught too. A cycle every edge of
+ * which is required is an error — no row of any resource in the cycle could
+ * ever be inserted. A cycle containing at least one nullable FK (an optional
+ * interface property) is breakable and reported as a warning.
+ */
+export declare function detectCycles(resources: ResourceModel[]): EntityDiagnostic[];

package/dist/compile/entities.js

@@ -0,0 +1,496 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeEntities = analyzeEntities;
+exports.detectCycles = detectCycles;
+const path = __importStar(require("path"));
+const ts = __importStar(require("typescript"));
+const program_1 = require("./program");
+function analyzeEntities(program, fileNames) {
+    const checker = program.getTypeChecker();
+    const diagnostics = [];
+    const sourceFiles = (0, program_1.resourceSourceFiles)(program, fileNames);
+    const scanned = new Set(sourceFiles.map((sf) => path.resolve(sf.fileName)));
+    // Every interface declared in the scanned files is a *candidate* entity.
+    const candidates = new Set();
+    for (const sf of sourceFiles) {
+        ts.forEachChild(sf, function walk(node) {
+            if (ts.isInterfaceDeclaration(node))
+                candidates.add(node);
+            ts.forEachChild(node, walk);
+        });
+    }
+    // 1. Roots: interfaces used as type arguments of hook calls, plus explicit
+    //    `@rastackResource` opt-ins.
+    const roots = [];
+    const rooted = new Set();
+    const addRoot = (decl) => {
+        if (!rooted.has(decl)) {
+            rooted.add(decl);
+            roots.push(decl);
+        }
+    };
+    for (const sf of sourceFiles) {
+        ts.forEachChild(sf, function walk(node) {
+            if (ts.isCallExpression(node) && isHookCall(node)) {
+                for (const typeArg of node.typeArguments ?? []) {
+                    const decl = interfaceBehindTypeNode(typeArg, checker, scanned);
+                    if (decl && candidates.has(decl))
+                        addRoot(decl);
+                }
+            }
+            ts.forEachChild(node, walk);
+        });
+    }
+    for (const decl of candidates) {
+        if (jsdocTags(decl).has("rastackresource"))
+            addRoot(decl);
+    }
+    // 2. Transitive closure over FK references: an entity's interface-typed
+    //    property pulls the referenced interface in as an entity too.
+    const propsByDecl = new Map();
+    const analyzed = (decl) => {
+        let props = propsByDecl.get(decl);
+        if (!props) {
+            props = analyzeProperties(decl, checker, scanned);
+            propsByDecl.set(decl, props);
+        }
+        return props;
+    };
+    const included = [];
+    const seen = new Set();
+    const queue = [...roots];
+    while (queue.length) {
+        const decl = queue.shift();
+        if (seen.has(decl))
+            continue;
+        seen.add(decl);
+        included.push(decl);
+        for (const prop of analyzed(decl)) {
+            if (prop.target && candidates.has(prop.target) && !seen.has(prop.target)) {
+                queue.push(prop.target);
+            }
+        }
+    }
+    // 3. Build the canonical models.
+    const namingByDecl = new Map(included.map((decl) => [decl, entityNaming(decl)]));
+    const resources = [];
+    for (const decl of included) {
+        const naming = namingByDecl.get(decl);
+        const key = `${naming.app}.${naming.model}`;
+        const fields = [];
+        const relations = [];
+        for (const prop of analyzed(decl)) {
+            if (prop.skip) {
+                diagnostics.push({ severity: "warning", message: `${key}.${prop.name}: ${prop.skip}` });
+                continue;
+            }
+            if (prop.inverse)
+                continue; // has-many arrays are the reverse side of a FK
+            if (prop.target) {
+                const target = namingByDecl.get(prop.target);
+                if (!target)
+                    continue; // unreachable: closure included every target
+                const field = {
+                    name: prop.name,
+                    type: "fk",
+                    relation: { app: target.app, model: target.model },
+                };
+                if (prop.nullable)
+                    field.null = true;
+                fields.push(field);
+                relations.push({
+                    field: prop.name,
+                    target: `${target.app}.${target.model}`,
+                    kind: "fk",
+                });
+            }
+            else if (prop.field) {
+                fields.push(prop.field);
+            }
+        }
+        resources.push({
+            app: naming.app,
+            model: naming.model,
+            fields,
+            relations,
+            search: naming.search,
+            permission: naming.permission,
+        });
+    }
+    resources.sort((a, b) => a.app === b.app ? a.model.localeCompare(b.model) : a.app.localeCompare(b.app));
+    return { resources, diagnostics };
+}
+// -- hooks -------------------------------------------------------------------
+/** A React-style hook call: `useX(...)` or `obj.useX(...)` with type args. */
+function isHookCall(call) {
+    if (!call.typeArguments?.length)
+        return false;
+    const callee = call.expression;
+    const name = ts.isIdentifier(callee)
+        ? callee.text
+        : ts.isPropertyAccessExpression(callee)
+            ? callee.name.text
+            : undefined;
+    return !!name && /^use[A-Z0-9_]/.test(name);
+}
+/** Resolve a type node to an interface declared in one of the scanned files. */
+function interfaceBehindTypeNode(node, checker, scanned) {
+    return interfaceBehindType(checker.getTypeFromTypeNode(node), scanned);
+}
+function interfaceBehindType(type, scanned) {
+    const symbol = type.aliasSymbol ?? type.getSymbol();
+    for (const decl of symbol?.declarations ?? []) {
+        if (ts.isInterfaceDeclaration(decl) &&
+            scanned.has(path.resolve(decl.getSourceFile().fileName))) {
+            return decl;
+        }
+    }
+    return undefined;
+}
+function analyzeProperties(decl, checker, scanned) {
+    const props = [];
+    for (const member of decl.members) {
+        if (!ts.isPropertySignature(member) || !member.type)
+            continue;
+        const name = ts.isIdentifier(member.name) || ts.isStringLiteralLike(member.name)
+            ? member.name.text
+            : undefined;
+        if (!name)
+            continue;
+        props.push(analyzeProperty(name, member, checker, scanned));
+    }
+    return props;
+}
+function analyzeProperty(name, member, checker, scanned) {
+    let nullable = !!member.questionToken;
+    // Unwrap parens and unions: strip null/undefined (→ nullable), and require a
+    // single remaining arm (unions of string literals collapse to `string`).
+    let typeNode = unwrapParens(member.type);
+    if (ts.isUnionTypeNode(typeNode)) {
+        const arms = typeNode.types.filter((t) => {
+            const isNullish = (ts.isLiteralTypeNode(t) && t.literal.kind === ts.SyntaxKind.NullKeyword) ||
+                t.kind === ts.SyntaxKind.UndefinedKeyword;
+            if (isNullish)
+                nullable = true;
+            return !isNullish;
+        });
+        if (arms.length > 1 && arms.every(isStringish)) {
+            return scalarProp(name, "string", configFromTags(jsdocTags(member)), nullable);
+        }
+        if (arms.length !== 1) {
+            return { name, nullable, skip: "unsupported union type — skipped" };
+        }
+        typeNode = unwrapParens(arms[0]);
+    }
+    // Arrays: `Entity[]` is the reverse side of a FK — it contributes no column
+    // but is intentionally not an error. Arrays of scalars have no manifest shape.
+    const element = arrayElement(typeNode);
+    if (element) {
+        if (interfaceBehindTypeNode(element, checker, scanned)) {
+            return { name, nullable, inverse: true };
+        }
+        return { name, nullable, skip: "array fields are not supported — skipped" };
+    }
+    const type = checker.getTypeFromTypeNode(typeNode);
+    const base = classifyType(type, scanned);
+    if (base === undefined) {
+        return { name, nullable, skip: "unsupported type — skipped" };
+    }
+    if (typeof base !== "string") {
+        return { name, nullable, target: base }; // entity interface → FK
+    }
+    const config = {
+        ...configFromTags(jsdocTags(member)),
+        ...configFromType(type, checker, member),
+    };
+    return scalarProp(name, base, config, nullable);
+}
+/**
+ * What a property type *is*: a manifest scalar, an entity interface (→ FK), or
+ * unsupported. Intersections classify by their first classifiable constituent,
+ * which is what lets `DbConfig` brands ride along — `string & Unique` is a
+ * string; the brand carries configuration, not a datatype.
+ */
+function classifyType(type, scanned) {
+    if (type.flags & ts.TypeFlags.StringLike)
+        return "string";
+    if (type.flags & ts.TypeFlags.NumberLike)
+        return "float";
+    if (type.flags & ts.TypeFlags.BooleanLike)
+        return "bool";
+    if (type.isIntersection()) {
+        for (const part of type.types) {
+            const classified = classifyType(part, scanned);
+            if (classified)
+                return classified;
+        }
+        return undefined;
+    }
+    if (type.getProperty("__rastackDb"))
+        return undefined; // a bare config brand
+    const decl = interfaceBehindType(type, scanned);
+    if (decl)
+        return decl;
+    if (type.getSymbol()?.getName() === "Date")
+        return "datetime";
+    return undefined;
+}
+/** Build a scalar field, letting the column config refine type + constraints. */
+function scalarProp(name, base, config, nullable) {
+    let type = base;
+    if (base === "float" && config.int)
+        type = "int";
+    if (base === "string" && config.uuid)
+        type = "uuid";
+    if (base === "string" && config.datetime)
+        type = "datetime";
+    const field = { name, type };
+    if (config.maxLength !== undefined)
+        field.maxLength = config.maxLength;
+    if (config.unique)
+        field.unique = true;
+    if (config.primaryKey)
+        field.primaryKey = true;
+    if (nullable)
+        field.null = true;
+    if (config.default !== undefined)
+        field.default = config.default;
+    return { name, nullable, field };
+}
+/**
+ * Config carried in the type system: intersecting a property type with
+ * `DbConfig` brands (`string & Unique & MaxLength<3>`, or a custom
+ * `interface Registration extends DbConfig<{…}>`) surfaces a phantom
+ * `__rastackDb` property whose literal type arguments are the configuration.
+ */
+function configFromType(type, checker, location) {
+    const config = {};
+    const symbol = type.getProperty("__rastackDb");
+    if (!symbol)
+        return config;
+    const carrier = checker
+        .getTypeOfSymbolAtLocation(symbol, location)
+        .getNonNullableType();
+    const prop = (name) => {
+        const p = carrier.getProperty(name);
+        return p && checker.getTypeOfSymbolAtLocation(p, location);
+    };
+    if (prop("int"))
+        config.int = true;
+    if (prop("uuid"))
+        config.uuid = true;
+    if (prop("datetime"))
+        config.datetime = true;
+    if (prop("unique"))
+        config.unique = true;
+    if (prop("primaryKey"))
+        config.primaryKey = true;
+    const maxLength = prop("maxLength");
+    if (maxLength?.isNumberLiteral())
+        config.maxLength = maxLength.value;
+    const dflt = prop("default");
+    const value = dflt ? literalValue(dflt, checker) : undefined;
+    if (value !== undefined)
+        config.default = value;
+    return config;
+}
+/** Config carried as JSDoc tags (`@unique`, `@maxLength 3`, `@default x`). */
+function configFromTags(tags) {
+    const config = {};
+    if (tags.has("int"))
+        config.int = true;
+    if (tags.has("uuid"))
+        config.uuid = true;
+    if (tags.has("datetime"))
+        config.datetime = true;
+    if (tags.has("unique"))
+        config.unique = true;
+    if (tags.has("primarykey"))
+        config.primaryKey = true;
+    const maxLength = Number(tags.get("maxlength"));
+    if (Number.isFinite(maxLength) && maxLength > 0)
+        config.maxLength = maxLength;
+    const dflt = tags.get("default");
+    if (dflt !== undefined) {
+        try {
+            config.default = JSON.parse(dflt);
+        }
+        catch {
+            config.default = dflt;
+        }
+    }
+    return config;
+}
+/** The JS value of a literal type (`"active"`, `0`, `true`), else undefined. */
+function literalValue(type, checker) {
+    if (type.isStringLiteral() || type.isNumberLiteral())
+        return type.value;
+    if (type.flags & ts.TypeFlags.BooleanLiteral) {
+        return checker.typeToString(type) === "true";
+    }
+    return undefined;
+}
+function unwrapParens(node) {
+    while (ts.isParenthesizedTypeNode(node))
+        node = node.type;
+    return node;
+}
+/** `string`, a string-literal type, or a template literal type. */
+function isStringish(node) {
+    if (node.kind === ts.SyntaxKind.StringKeyword)
+        return true;
+    if (ts.isLiteralTypeNode(node) && ts.isStringLiteralLike(node.literal))
+        return true;
+    return ts.isTemplateLiteralTypeNode(node);
+}
+/** Element type of `T[]` / `Array<T>` / `ReadonlyArray<T>`, else undefined. */
+function arrayElement(node) {
+    if (ts.isArrayTypeNode(node))
+        return node.elementType;
+    if (ts.isTypeReferenceNode(node) &&
+        ts.isIdentifier(node.typeName) &&
+        (node.typeName.text === "Array" || node.typeName.text === "ReadonlyArray") &&
+        node.typeArguments?.length === 1) {
+        return node.typeArguments[0];
+    }
+    return undefined;
+}
+function entityNaming(decl) {
+    const tags = jsdocTags(decl);
+    const raw = decl.name.text;
+    // Generated entity interfaces are `I`-prefixed (`IFlight`); strip the prefix
+    // so hook usage of generated types resolves to the same resource.
+    const stripped = /^I[A-Z]/.test(raw) ? raw.slice(1) : raw;
+    const model = tags.get("rastackmodel") || stripped.charAt(0).toLowerCase() + stripped.slice(1);
+    const app = tags.get("rastackapp") ||
+        path
+            .basename(decl.getSourceFile().fileName)
+            .replace(/\.(ts|tsx)$/, "")
+            .toLowerCase();
+    const naming = { app, model };
+    const search = tags.get("rastacksearch");
+    if (search)
+        naming.search = search.split(",").map((s) => s.trim()).filter(Boolean);
+    const permission = tags.get("rastackpermission");
+    if (permission === "authenticatedOrReadOnly" ||
+        permission === "authenticated" ||
+        permission === "public") {
+        naming.permission = permission;
+    }
+    return naming;
+}
+/** All JSDoc tags on a node, keyed by lower-cased tag name → comment text. */
+function jsdocTags(node) {
+    const tags = new Map();
+    for (const tag of ts.getJSDocTags(node)) {
+        const text = ts.getTextOfJSDocComment(tag.comment) ?? "";
+        tags.set(tag.tagName.text.toLowerCase(), text.trim());
+    }
+    return tags;
+}
+// -- circular-dependency detection ---------------------------------------------
+/**
+ * Detect cycles in the FK graph. Works on the *merged* resource set, so cycles
+ * authored through the `resource()` DSL are caught too. A cycle every edge of
+ * which is required is an error — no row of any resource in the cycle could
+ * ever be inserted. A cycle containing at least one nullable FK (an optional
+ * interface property) is breakable and reported as a warning.
+ */
+function detectCycles(resources) {
+    const adjacency = new Map();
+    for (const r of resources) {
+        const from = `${r.app}.${r.model}`;
+        const edges = [];
+        for (const rel of r.relations) {
+            const field = r.fields.find((f) => f.name === rel.field);
+            edges.push({
+                from,
+                to: rel.target,
+                field: rel.field,
+                nullable: field?.null === true,
+            });
+        }
+        adjacency.set(from, edges);
+    }
+    const diagnostics = [];
+    const reported = new Set();
+    const state = new Map(); // 1 = on stack, 2 = done
+    const stack = [];
+    const reportCycle = (closingEdge) => {
+        const start = stack.findIndex((frame) => frame.node === closingEdge.to);
+        const nodes = stack.slice(start).map((frame) => frame.node);
+        const edges = [
+            ...stack.slice(start + 1).map((frame) => frame.edgeIn),
+            closingEdge,
+        ];
+        const key = [...nodes].sort().join("|");
+        if (reported.has(key))
+            return;
+        reported.add(key);
+        const chain = [...nodes, closingEdge.to].join(" → ");
+        const breakable = edges.find((e) => e.nullable);
+        diagnostics.push(breakable
+            ? {
+                severity: "warning",
+                message: `Circular dependency: ${chain} — breakable via nullable ` +
+                    `field ${breakable.from}.${breakable.field}.`,
+            }
+            : {
+                severity: "error",
+                message: `Circular dependency: ${chain} — every foreign key in the ` +
+                    `cycle is required, so no row can ever be inserted. Make ` +
+                    `one of the fields optional to break the cycle.`,
+            });
+    };
+    const visit = (node, edgeIn) => {
+        state.set(node, 1);
+        stack.push({ node, edgeIn });
+        for (const edge of adjacency.get(node) ?? []) {
+            const targetState = state.get(edge.to);
+            if (targetState === 1)
+                reportCycle(edge);
+            else if (targetState !== 2)
+                visit(edge.to, edge);
+        }
+        stack.pop();
+        state.set(node, 2);
+    };
+    for (const node of adjacency.keys()) {
+        if (!state.has(node))
+            visit(node);
+    }
+    return diagnostics;
+}

package/dist/compile/index.d.ts

@@ -1,5 +1,8 @@
+import { EntityDiagnostic } from "./entities";
 import { Manifest, ResourceModel } from "./model";
 export { analyze } from "./analyze";
+export { analyzeEntities, detectCycles } from "./entities";
+export type { EntityAnalysis, EntityDiagnostic } from "./entities";
 export { buildManifest } from "./manifest";
 export { buildOpenApi } from "./openapi";
 export * from "./model";
@@ -7,17 +10,31 @@ export interface CompileResult {
     manifest: Manifest;
     openapi: any;
     files: string[];
+    diagnostics: EntityDiagnostic[];
 }
 /**
- * Every `.ts` resource file under a directory (recursively), or an explicit
- * file. Recursion is what lets resource definitions live **co-located with the
- * pages that consume them** — e.g. `app/airports/_schema.rad.ts` beside
- * `app/airports/index.tsx` — instead of in one top-level `resources/` folder.
- * `.tsx` route components and `.d.ts` files are skipped; only files with a
- * `resource(...)` call contribute to the manifest, so co-located helpers are
- * harmless.
+ * Every `.ts`/`.tsx` source file under a directory (recursively), or an
+ * explicit file. Recursion is what lets resource definitions live **co-located
+ * with the pages that consume them** — e.g. `app/airports/_schema.rastack.ts`
+ * beside `app/airports/index.tsx` — instead of in one top-level `resources/`
+ * folder. `.tsx` files carry no `resource(...)` definitions but are scanned
+ * for the typed hook calls (`useEntityList<Airport>(…)`) that root the
+ * interface-driven entity graph; co-located helpers are harmless.
  */
 export declare function resolveResourceFiles(input: string): string[];
+export interface ProjectAnalysis {
+    resources: ResourceModel[];
+    diagnostics: EntityDiagnostic[];
+}
+/**
+ * Analyse a project into the canonical model: explicit `resource()` DSL
+ * definitions plus resources inferred from hook-rooted TypeScript interfaces.
+ * When both surfaces define the same `app.model`, the explicit DSL definition
+ * wins — hook usage of a generated `IAirport` interface resolves back onto the
+ * authored resource instead of creating a duplicate. Cycle detection runs over
+ * the merged FK graph.
+ */
+export declare function analyzeProject(input: string): ProjectAnalysis;
 /** Analyse resource definitions into the canonical model (no file output). */
 export declare function analyzeResources(input: string): ResourceModel[];
 /** Compile resource definitions to a manifest + OpenAPI, writing both to disk. */