@facilis.dev/analyze 0.0.0-stage → 0.1.0

package/src/types-graph.ts

@@ -0,0 +1,161 @@
+// Graph-facing fact shapes (the project graph's public model), split from types.ts so the
+// base fact model stays under the 300-line source limit. Static screen preview/link facts live
+// here too because they are attached to page nodes and page-link edges.
+
+import type {
+  ColumnFact,
+  ElevationFact,
+  HttpMethod,
+  PageKind,
+  RouteInputFact,
+  ScopeFact,
+  SourceRef,
+  WrapperState,
+} from "./types.ts";
+
+export type GraphNodeKind = "page" | "route" | "table" | "view" | "workflow";
+
+export interface PageNodeData {
+  readonly kind: "page";
+  readonly pagePath: string;
+  readonly pageKind: PageKind;
+  readonly callCount: number;
+  /** URL paths from the explicit route table; absent when the page is unrouted. */
+  readonly routePaths?: readonly string[];
+  /** Static component structure used by the graph's page inspector. */
+  readonly preview?: PagePreview;
+}
+
+export interface RouteNodeData {
+  readonly kind: "route";
+  readonly method: HttpMethod;
+  readonly path: string;
+  readonly permission: readonly string[];
+  readonly wrapper: WrapperState;
+  /** Presence of the handler's input schemas (body/form/query/params), from the AST. */
+  readonly input: RouteInputFact;
+  readonly dbTables: readonly string[];
+  readonly dbColumns: readonly string[];
+  /** Audited sudo/system calls, carried for the graph's elevation badge. */
+  readonly elevations?: readonly ElevationFact[];
+  /** The wrapper config's one-sentence description, or null when absent (D-129). */
+  readonly description: string | null;
+  readonly unknown: boolean;
+}
+
+export interface TableNodeData {
+  readonly kind: "table";
+  readonly table: string;
+  readonly columns: readonly ColumnFact[];
+  readonly rlsEnabled: boolean;
+  readonly scope: ScopeFact | null;
+  /**
+   * True when an installed @facilis.dev package declares the table and the project only
+   * re-exports it: its source file lives under `node_modules/`.
+   */
+  readonly framework: boolean;
+  readonly unknown: boolean;
+}
+
+/** A declarative view declared with defineView under db/views (D-097/D-098, D-160). */
+export interface ViewNodeData {
+  readonly kind: "view";
+  /** The view's SQL name: what a route declares in `dbTables` (D-157). */
+  readonly view: string;
+  /** Base tables named by the declaration (metadata only, D-097); [] when absent. */
+  readonly tables: readonly string[];
+  /** The view's own permission; null keeps the invoker behaviour (D-098). */
+  readonly permission: string | null;
+  /** null when a declared permission could not be read, so the mode is unknown. */
+  readonly access: "invoker" | "definer" | null;
+  readonly unknown: boolean;
+}
+
+/** One step of a workflow definition, as the graph inspector shows it. */
+export interface WorkflowStepNodeData {
+  readonly index: number;
+  readonly kind: "job" | "approval";
+  /** Job name or approval title key; null when the definition could not be read. */
+  readonly name: string | null;
+  readonly permission: string | null;
+  /** Forward step index declared by `onReject.step`, when present. */
+  readonly onRejectStep: number | null;
+}
+
+/** A workflow definition read from `server/workflows/**` (D-135 W3). */
+export interface WorkflowNodeData {
+  readonly kind: "workflow";
+  readonly name: string;
+  readonly steps: readonly WorkflowStepNodeData[];
+  readonly unknown: boolean;
+}
+
+export type GraphNodeData =
+  PageNodeData | RouteNodeData | TableNodeData | ViewNodeData | WorkflowNodeData;
+
+export interface GraphNode {
+  readonly id: string;
+  readonly kind: GraphNodeKind;
+  readonly label: string;
+  readonly sourceFile: string | null;
+  readonly data: GraphNodeData;
+}
+
+export type GraphEdgeKind =
+  "fk" | "relation" | "route-table" | "page-route" | "page-link" | "route-view" | "view-base";
+
+export interface GraphEdge {
+  readonly id: string;
+  readonly kind: GraphEdgeKind;
+  readonly source: string;
+  readonly target: string;
+  readonly label: string | null;
+  /** A route-table/route-view edge reached through audited sudo/system elevation. */
+  readonly access?: "elevated";
+}
+
+export interface ProjectGraph {
+  readonly nodes: readonly GraphNode[];
+  readonly edges: readonly GraphEdge[];
+}
+
+/** One node of the bounded static structure preview attached to a page. */
+export interface PagePreviewNode {
+  readonly id: string;
+  readonly parentId: string | null;
+  /** Component name as written in the JSX (`TodosPage`, `Page`, `header`). */
+  readonly name: string;
+  readonly kind: "component" | "intrinsic" | "slot";
+  /** Project file that defines the component, when it can be resolved statically. */
+  readonly file: string | null;
+  readonly source: SourceRef;
+  /** True when the node sits under a conditional/map branch. */
+  readonly dynamic: boolean;
+}
+
+/** Static component structure of one page, capped by the analyzer. */
+export interface PagePreview {
+  /** URL paths resolved from the explicit route table. */
+  readonly routePaths: readonly string[];
+  readonly nodes: readonly PagePreviewNode[];
+  /** True when the maximum depth/node budget cut the structure. */
+  readonly truncated: boolean;
+}
+
+/** An explicit client-side navigation target (`Link`, `NavLink`, `navigate()`). */
+export interface PageLink {
+  /** Page file that renders the link. */
+  readonly from: string;
+  /** Target page file, resolved through the route table. */
+  readonly to: string;
+  /** URL path written in the source, for the edge label. */
+  readonly toPath: string;
+  readonly kind: "link" | "navlink" | "navigate";
+  readonly source: SourceRef;
+}
+
+/** Static screen facts consumed by the graph builder (not a separate analysis output). */
+export interface ScreenFacts {
+  readonly previews: Readonly<Record<string, PagePreview>>;
+  readonly links: readonly PageLink[];
+}

package/src/types-jobs.ts

@@ -0,0 +1,40 @@
+// Background-job fact model, split from types.ts so the base fact model stays under the
+// 300-line source limit. A job always runs system-scoped (D-107), so D-157 applies to its
+// `db` client without the elevation dimension routes have: no `ctx.sudo`/`ctx.system`.
+
+import type { RouteRelationUse } from "./types-relations.ts";
+import type { SourceRef, UnknownFact } from "./types.ts";
+
+/** One `server/jobs/**` definition: the `defineJob({...})` default export. */
+export interface JobFact {
+  readonly name: string;
+  readonly sourceFile: string;
+  readonly source: SourceRef;
+  /** Relations the definition declares; null when not statically readable (D-157). */
+  readonly dbTables: readonly string[] | null;
+  /** true allows `db.execute`; false when absent; null when unreadable (fail closed). */
+  readonly rawSql: boolean | null;
+  readonly unknown: readonly UnknownFact[];
+}
+
+/** Static db usage of one job's `run(ctx)` body, following project-local calls (D-157). */
+export interface JobRelationsFact {
+  readonly used: readonly RouteRelationUse[];
+  readonly unresolved: readonly SourceRef[];
+  /** `db.execute(...)` call sites; legal only with rawSql: true. */
+  readonly rawSql: readonly SourceRef[];
+  /** A project-external callee received the job's db client, so usage is incomplete. */
+  readonly opaque: boolean;
+}
+
+/**
+ * Usage of a job whose `run` the pass cannot inspect: explicitly empty, never guessed.
+ * `opaque` is true because "not observed" must not be reported as "never used" (the
+ * declared-but-unused warning and the AI rule both suppress on it).
+ */
+export const EMPTY_JOB_RELATIONS: JobRelationsFact = {
+  used: [],
+  unresolved: [],
+  rawSql: [],
+  opaque: true,
+};

package/src/types-relations.ts

@@ -0,0 +1,64 @@
+// Route relation-usage and view facts (D-157), split from types.ts so the base fact model
+// stays under the 300-line source limit. A fact that cannot be determined is explicit:
+// an empty usage is "nothing observed", never "nothing to check".
+
+import type { ElevationKind, SourceRef, UnknownFact } from "./types.ts";
+
+/** A view declared with defineView under db/views/ (D-097/D-098). Not a graph node (D-157). */
+export interface ViewFact {
+  readonly name: string;
+  /** TypeScript binding holding the view, when declared as a const. */
+  readonly binding: string | null;
+  /** Base tables named by the declaration (metadata only, D-097); [] when absent. */
+  readonly tables: readonly string[];
+  /** The view's own permission; null keeps the invoker behaviour (D-098). */
+  readonly permission: string | null;
+  /** null when a declared permission could not be read, so the mode is unknown. */
+  readonly access: "invoker" | "definer" | null;
+  readonly source: SourceRef;
+  readonly unknown: readonly UnknownFact[];
+}
+
+/** One relation (table or view) a route reaches through a db client. */
+export interface RouteRelationUse {
+  readonly name: string;
+  /** The use site, so a finding can jump to the expression. */
+  readonly source: SourceRef;
+}
+
+/** What one audited elevation callback reaches through its elevated db client (D-157). */
+export interface RouteElevationUsage {
+  readonly kind: ElevationKind;
+  /** The ctx.sudo / ctx.system call site. */
+  readonly source: SourceRef;
+  /** The elevation's own `tables` option; [] when unknown. */
+  readonly tables: readonly string[];
+  readonly used: readonly RouteRelationUse[];
+  readonly unresolved: readonly SourceRef[];
+  /** The elevation's `tables` option is missing or not statically readable. */
+  readonly tablesUnknown: boolean;
+  /** The elevated client reached a callee outside the project graph. */
+  readonly opaque: boolean;
+}
+
+/** Static db usage of one route handler, following project-local helper calls (D-157). */
+export interface RouteRelationsFact {
+  /** Relations reached through ctx.db outside elevations, deduplicated by name. */
+  readonly used: readonly RouteRelationUse[];
+  /** Dynamic/unresolvable relation expressions, and uses the pass could not inspect. */
+  readonly unresolved: readonly SourceRef[];
+  /** `db.execute(...)` call sites; legal only with rawSql: true. */
+  readonly rawSql: readonly SourceRef[];
+  /** A project-external callee received the route's db client, so usage is incomplete. */
+  readonly opaque: boolean;
+  readonly elevations: readonly RouteElevationUsage[];
+}
+
+/** Usage of a route the pass cannot scan (invalid wrapper): explicitly empty, not unknown. */
+export const EMPTY_ROUTE_RELATIONS: RouteRelationsFact = {
+  used: [],
+  unresolved: [],
+  rawSql: [],
+  opaque: false,
+  elevations: [],
+};

package/src/types-workflows.ts

@@ -0,0 +1,42 @@
+// Workflow fact shapes, split from types.ts so the base fact model stays under the 300-line
+// source limit (D-135 W3). They are re-exported from types.ts, so existing imports keep working.
+
+import type { SourceRef, UnknownFact } from "./types.ts";
+
+/** One step of a `defineWorkflow` chain, as the static subset reads it. */
+export interface WorkflowStepFact {
+  readonly index: number;
+  readonly kind: "job" | "approval";
+  /** Job name for a job step, approval title key for an approval step. */
+  readonly name: string | null;
+  /** Approval assignment permission, when the definition declares one. */
+  readonly permission: string | null;
+  /** Forward step index declared by `onReject.step`, when present. */
+  readonly onRejectStep: number | null;
+  readonly source: SourceRef;
+}
+
+/** One `server/workflows/**` definition. */
+export interface WorkflowFact {
+  readonly name: string;
+  readonly sourceFile: string;
+  readonly source: SourceRef;
+  readonly steps: readonly WorkflowStepFact[];
+  readonly unknown: readonly UnknownFact[];
+}
+
+/**
+ * Table surface of a workflow, derived from the jobs its steps reference (never declared):
+ * the sorted union of the referenced jobs' own `dbTables` (tables and views alike).
+ */
+export interface WorkflowTablesFact {
+  readonly name: string;
+  readonly sourceFile: string;
+  readonly source: SourceRef;
+  /** Sorted unique union of the referenced jobs' declared dbTables. */
+  readonly tables: readonly string[];
+  /** Job-step names with no definition under `server/jobs/**`; [] when all resolve. */
+  readonly unknownJobs: readonly string[];
+  /** True when a referenced job's dbTables is unreadable, so the union is incomplete. */
+  readonly unknown: boolean;
+}

package/src/types.ts

@@ -0,0 +1,299 @@
+import type { JobFact, JobRelationsFact } from "./types-jobs.ts";
+import type { RouteRelationsFact, ViewFact } from "./types-relations.ts";
+import type { ProjectGraph } from "./types-graph.ts";
+import type { WorkflowFact, WorkflowTablesFact } from "./types-workflows.ts";
+
+/**
+ * Fact model of the AST analyzer (docs/findings/ast-dsl-contract.md).
+ *
+ * Facts are parser-independent and always carry their source. A fact that cannot be
+ * determined is represented explicitly (null or an unknown entry), never as an empty value:
+ * in particular "dbTables unknown" (null) is not "no DB tables" ([]).
+ */
+
+export interface SourceRef {
+  readonly file: string;
+  readonly line: number;
+}
+
+export interface UnknownFact {
+  readonly code: string;
+  readonly reason: string;
+  readonly source: SourceRef;
+}
+
+export type Severity = "error" | "warning" | "info";
+
+export interface Diagnostic {
+  readonly code: string;
+  readonly severity: Severity;
+  readonly message: string;
+  readonly source: SourceRef | null;
+}
+
+export interface LocaleCatalogs {
+  readonly [locale: string]: Readonly<Record<string, string>>;
+}
+
+// ── config ──────────────────────────────────────────────────────────────────────────
+
+export interface ConfigFacts {
+  readonly parsed: boolean;
+  readonly source: SourceRef | null;
+  readonly permissions: readonly string[];
+  readonly roles: Readonly<Record<string, readonly string[]>>;
+  readonly defaultRole: string | null;
+  readonly defaultLocale: string | null;
+  readonly locales: readonly string[];
+  readonly migrationsDir: string;
+  readonly tenantColumns: readonly string[];
+  readonly ownerColumns: readonly string[];
+  readonly unknown: readonly UnknownFact[];
+}
+
+// ── schema ──────────────────────────────────────────────────────────────────────────
+
+export type ColumnDefaultKind = "literal" | "now" | "random" | "unknown";
+
+export interface ColumnDefaultFact {
+  readonly kind: ColumnDefaultKind;
+  readonly value: string | null;
+}
+
+export interface ForeignKeyFact {
+  readonly columns: readonly string[];
+  readonly targetTable: string;
+  readonly targetColumns: readonly string[];
+  readonly onDelete: string | null;
+  readonly onUpdate: string | null;
+  readonly source: SourceRef;
+}
+
+export interface ColumnFact {
+  /** Drizzle property key in the table object (the dbColumns domain). */
+  readonly property: string;
+  /** SQL column name (first literal argument of the builder, or the property key). */
+  readonly name: string;
+  readonly builder: string;
+  /** Display type derived from the builder and its arguments. */
+  readonly type: string;
+  readonly notNull: boolean;
+  readonly primaryKey: boolean;
+  readonly unique: boolean;
+  readonly default: ColumnDefaultFact | null;
+  readonly source: SourceRef;
+  readonly unknown: readonly UnknownFact[];
+}
+
+export type PolicyCommand = "SELECT" | "INSERT" | "UPDATE" | "DELETE" | "ALL";
+
+export interface PolicyFact {
+  readonly name: string;
+  readonly command: PolicyCommand;
+  readonly restrictive: boolean;
+  readonly source: SourceRef;
+  readonly unknown: readonly UnknownFact[];
+}
+
+export interface ScopeFact {
+  readonly column: string;
+  readonly kind: "tenant" | "owner";
+}
+
+export interface TableFact {
+  readonly name: string;
+  /** TypeScript binding holding the table, when declared as a const. */
+  readonly binding: string | null;
+  readonly columns: readonly ColumnFact[];
+  readonly primaryKey: readonly string[];
+  readonly foreignKeys: readonly ForeignKeyFact[];
+  readonly policies: readonly PolicyFact[];
+  readonly rlsEnabled: boolean;
+  readonly scope: ScopeFact | null;
+  readonly source: SourceRef;
+  readonly unknown: readonly UnknownFact[];
+}
+
+export interface RelationFact {
+  readonly from: string;
+  readonly to: string;
+  readonly cardinality: "one" | "many";
+  readonly fields: readonly string[];
+  readonly references: readonly string[];
+  readonly source: SourceRef;
+  readonly unknown: readonly UnknownFact[];
+}
+
+// ── routes ─────────────────────────────────────────────────────────────────────────
+
+export type HttpMethod =
+  "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "TRACE" | "CONNECT" | "ALL";
+
+export type WrapperState = "valid" | "invalid" | "unknown";
+
+export interface RouteInputFact {
+  readonly body: boolean;
+  /** A multipart/form-data schema (D-053); mutually exclusive with `body`. */
+  readonly form: boolean;
+  readonly query: boolean;
+  readonly params: boolean;
+}
+
+export type ElevationKind = "sudo" | "system";
+
+/** One audited elevation call in a route handler (D-099): `ctx.sudo` / `ctx.system`. */
+export interface ElevationFact {
+  readonly kind: ElevationKind;
+  /** Tables passed to the elevation; [] when the array cannot be read statically. */
+  readonly tables: readonly string[];
+  /** The audit operation label, when statically readable. */
+  readonly operation: string | null;
+  readonly source: SourceRef;
+  readonly unknown: readonly UnknownFact[];
+}
+
+export interface RouteFact {
+  readonly method: HttpMethod;
+  readonly path: string;
+  readonly sourceFile: string;
+  readonly source: SourceRef;
+  readonly wrapper: WrapperState;
+  /** null = unknown; [] = explicitly public. */
+  readonly permission: readonly string[] | null;
+  /**
+   * True when the wrapper declares the route callable from another origin; false when absent;
+   * null when the declaration cannot be read statically (a cross-origin route is never assumed).
+   */
+  readonly crossSite: boolean | null;
+  /** null = unknown; [] = explicitly no DB. */
+  readonly dbTables: readonly string[] | null;
+  /** null = unknown; [] = explicitly no columns. */
+  readonly dbColumns: readonly string[] | null;
+  /** rawSql: true allows `db.execute` (D-157); false when absent; null when unreadable. */
+  readonly rawSql: boolean | null;
+  /** Static db usage of the handler, project-local helper calls followed (D-157). */
+  readonly relations: RouteRelationsFact;
+  readonly description: string | null;
+  readonly input: RouteInputFact;
+  /** True when the handler body reads the request body (SPEC §9.3 rule 8). */
+  readonly handlerBodyRead: boolean;
+  /** True when the handler body reads the multipart form (SPEC §9.3 rule 8, D-053). */
+  readonly handlerFormRead: boolean;
+  /** Audited elevation calls in the handler, in source order. */
+  readonly elevations: readonly ElevationFact[];
+  readonly unknown: readonly UnknownFact[];
+}
+
+// ── per-file module facts ──────────────────────────────────────────────────────────
+
+export type ImportKind =
+  "named" | "default" | "namespace" | "side-effect" | "export-from" | "dynamic" | "require";
+
+/** One module reference of a source file: static import, re-export, dynamic import or require. */
+export interface ImportFact {
+  readonly specifier: string;
+  readonly kind: ImportKind;
+  /** Local binding the reference introduces; null for side-effect/re-export/dynamic forms. */
+  readonly local: string | null;
+  /** Imported name for named imports ("default" for a default import); null otherwise. */
+  readonly imported: string | null;
+  readonly source: SourceRef;
+}
+
+/** One literal `t("key")` call; interpolated keys are skipped because they are not static. */
+export interface TranslationCallFact {
+  readonly key: string;
+  readonly source: SourceRef;
+}
+
+/** One call to a bare identifier (`drizzle(...)`, `t(...)`): enough for the security rules. */
+export interface CallFact {
+  readonly name: string;
+  readonly source: SourceRef;
+}
+
+export interface FileFacts {
+  /** Project-relative path of the parsed source file. */
+  readonly path: string;
+  readonly imports: readonly ImportFact[];
+  readonly translationCalls: readonly TranslationCallFact[];
+  readonly calls: readonly CallFact[];
+}
+
+// ── pages / client consumers ───────────────────────────────────────────────────────
+
+export type PageKind = "page" | "component" | "lib" | "other";
+
+export type PathKind = "literal" | "concat" | "template" | "builder" | "dynamic" | "unknown";
+
+export interface RouteCallFact {
+  readonly expression: string;
+  readonly kind: PathKind;
+  readonly staticPrefix: string | null;
+  readonly matchedRouteIds: readonly string[];
+  readonly source: SourceRef;
+  readonly unknown: readonly UnknownFact[];
+}
+
+export interface PageFact {
+  readonly path: string;
+  readonly kind: PageKind;
+  readonly calls: readonly RouteCallFact[];
+  readonly source: SourceRef;
+  readonly unknown: readonly UnknownFact[];
+}
+
+// ── graph ──────────────────────────────────────────────────────────────────────────
+// The graph-facing shapes live in types-graph.ts (the 300-line split); they are re-exported
+// here so every existing `from "./types.ts"` import keeps working.
+
+export type {
+  GraphEdge,
+  GraphEdgeKind,
+  GraphNode,
+  GraphNodeData,
+  GraphNodeKind,
+  PageLink,
+  PageNodeData,
+  PagePreview,
+  PagePreviewNode,
+  ProjectGraph,
+  RouteNodeData,
+  ScreenFacts,
+  TableNodeData,
+  ViewNodeData,
+  WorkflowNodeData,
+  WorkflowStepNodeData,
+} from "./types-graph.ts";
+export type {
+  RouteElevationUsage,
+  RouteRelationUse,
+  RouteRelationsFact,
+  ViewFact,
+} from "./types-relations.ts";
+export type { WorkflowFact, WorkflowStepFact, WorkflowTablesFact } from "./types-workflows.ts";
+
+// ── analysis ───────────────────────────────────────────────────────────────────────
+
+export interface Analysis {
+  readonly revision: string;
+  readonly files: readonly string[];
+  readonly config: ConfigFacts;
+  readonly routes: readonly RouteFact[];
+  readonly tables: readonly TableFact[];
+  readonly relations: readonly RelationFact[];
+  /** Declarative views (D-157): facts, and graph nodes since D-160. */
+  readonly views: readonly ViewFact[];
+  readonly pages: readonly PageFact[];
+  readonly workflows: readonly WorkflowFact[];
+  /** Job definitions, with D-157 applied to the db client their `run` body sees. */
+  readonly jobs: readonly JobFact[];
+  readonly jobRelations: Readonly<Record<string, JobRelationsFact>>;
+  /** Each workflow's table surface, derived from the jobs its steps reference. */
+  readonly workflowTables: readonly WorkflowTablesFact[];
+  /** Module facts for every parsed source file, in path order. */
+  readonly fileFacts: readonly FileFacts[];
+  readonly locales: LocaleCatalogs;
+  readonly diagnostics: readonly Diagnostic[];
+  readonly graph: ProjectGraph;
+}