@facilis.dev/analyze 0.0.0-stage → 0.1.0

package/src/graph-edges.ts

@@ -0,0 +1,167 @@
+// The project graph's edges (D-092, views since D-160), split from graph.ts so both files stay
+// under the 300-line source limit. Every edge points at a node the same analysis produced: the
+// caller passes the node ids and an edge whose endpoint is missing is dropped, because a
+// declaration that names a relation the project does not declare is not a graph fact.
+import type { GraphEdge, RouteFact, TableFact } from "./types.ts";
+import type { GraphInput } from "./graph.ts";
+import { pageId, routeId, tableId, viewId } from "./graph-ids.ts";
+
+function fkLabel(
+  table: TableFact,
+  targetTable: string,
+  targetColumns: readonly string[],
+  onDelete: string | null,
+): string {
+  let label = table.name + " -> " + targetTable + "." + targetColumns.join(", ");
+  if (onDelete !== null) label += " on delete " + onDelete;
+  return label;
+}
+
+function relationLabel(cardinality: "one" | "many"): string {
+  return cardinality;
+}
+
+function buildTableLookupMap(tables: readonly TableFact[]): Map<string, TableFact> {
+  const byName = new Map<string, TableFact>();
+  for (const table of tables) {
+    if (!byName.has(table.name)) byName.set(table.name, table);
+  }
+  return byName;
+}
+
+function elevatedTables(route: RouteFact): ReadonlySet<string> {
+  const tables = new Set<string>();
+  for (const elevation of route.elevations) {
+    for (const table of elevation.tables) tables.add(table);
+  }
+  return tables;
+}
+
+export function collectEdges(input: GraphInput, nodeIds: ReadonlySet<string>): GraphEdge[] {
+  const edges = new Map<string, GraphEdge>();
+  const tablesByName = buildTableLookupMap(input.tables);
+  // Tables and views share the SQL namespace, so a relation name is at most one of the two.
+  const viewNames = new Set(input.views.map((view) => view.name));
+  const add = (edge: GraphEdge): void => {
+    if (!nodeIds.has(edge.source) || !nodeIds.has(edge.target)) return;
+    if (edges.has(edge.id)) return;
+    edges.set(edge.id, edge);
+  };
+
+  for (const table of input.tables) {
+    for (const foreignKey of table.foreignKeys) {
+      add({
+        id:
+          "fk:" +
+          table.name +
+          ":" +
+          foreignKey.columns.join(",") +
+          ":" +
+          foreignKey.targetTable +
+          ":" +
+          foreignKey.targetColumns.join(","),
+        kind: "fk",
+        source: tableId(table.name),
+        target: tableId(foreignKey.targetTable),
+        label: fkLabel(
+          table,
+          foreignKey.targetTable,
+          foreignKey.targetColumns,
+          foreignKey.onDelete,
+        ),
+      });
+    }
+  }
+
+  for (const relation of input.relations) {
+    const id = ["relation", relation.from, relation.to, relation.cardinality];
+    if (relation.fields.length > 0) id.push(relation.fields.join(","));
+    if (relation.references.length > 0) id.push(relation.references.join(","));
+    add({
+      id: id.join(":"),
+      kind: "relation",
+      source: tableId(relation.from),
+      target: tableId(relation.to),
+      label: relationLabel(relation.cardinality),
+    });
+  }
+
+  // A view depends on the base tables its declaration names (metadata only, D-097). The target
+  // is a view when a view declares another view as its base, so the edge lands on the node that
+  // exists rather than on a phantom table.
+  for (const view of input.views) {
+    const source = viewId(view.name);
+    for (const base of view.tables) {
+      if (base === view.name) continue;
+      add({
+        id: "view-base:" + view.name + ":" + base,
+        kind: "view-base",
+        source,
+        target: viewNames.has(base) ? viewId(base) : tableId(base),
+        label: null,
+      });
+    }
+  }
+
+  for (const route of input.routes) {
+    const routeNodeId = routeId(route);
+    const elevated = elevatedTables(route);
+    // A route declares every relation it touches in dbTables (D-157), tables and views alike:
+    // the target kind is decided by the relation the name denotes.
+    for (const name of route.dbTables ?? []) {
+      const isView = viewNames.has(name);
+      add({
+        id: (isView ? "route-view:" : "route-table:") + routeNodeId + ":dbTables:" + name,
+        kind: isView ? "route-view" : "route-table",
+        source: routeNodeId,
+        target: isView ? viewId(name) : tableId(name),
+        label: "dbTables",
+        ...(elevated.has(name) ? { access: "elevated" as const } : {}),
+      });
+    }
+    for (const entry of route.dbColumns ?? []) {
+      const separator = entry.indexOf(".");
+      if (separator <= 0) continue;
+      const tableName = entry.slice(0, separator);
+      const columnName = entry.slice(separator + 1);
+      const table = tablesByName.get(tableName);
+      const knownColumn = table?.columns.some((column) => column.property === columnName);
+      if (knownColumn !== true) continue;
+      add({
+        id: "route-table:" + routeNodeId + ":dbColumns:" + tableName,
+        kind: "route-table",
+        source: routeNodeId,
+        target: tableId(tableName),
+        label: "dbColumns",
+        ...(elevated.has(tableName) ? { access: "elevated" as const } : {}),
+      });
+    }
+  }
+
+  for (const page of input.pages) {
+    const source = pageId(page.path);
+    for (const call of page.calls) {
+      for (const matchedRouteId of call.matchedRouteIds) {
+        add({
+          id: "page-route:" + page.path + ":" + matchedRouteId,
+          kind: "page-route",
+          source,
+          target: matchedRouteId,
+          label: null,
+        });
+      }
+    }
+  }
+
+  for (const link of input.screens?.links ?? []) {
+    add({
+      id: "page-link:" + link.from + ":" + link.to + ":" + link.kind + ":" + link.toPath,
+      kind: "page-link",
+      source: pageId(link.from),
+      target: pageId(link.to),
+      label: link.toPath,
+    });
+  }
+
+  return [...edges.values()];
+}

package/src/graph-ids.ts

@@ -0,0 +1,31 @@
+// The project graph's node ids (D-092): one spelling shared by the node builder in graph.ts
+// and the edge builder in graph-edges.ts, so an edge endpoint can never drift from its node.
+import type { RouteFact } from "./types.ts";
+
+const NODE_PREFIX = {
+  page: "page:",
+  route: "route:",
+  table: "table:",
+  view: "view:",
+  workflow: "workflow:",
+} as const;
+
+export function tableId(name: string): string {
+  return NODE_PREFIX.table + name;
+}
+
+export function viewId(name: string): string {
+  return NODE_PREFIX.view + name;
+}
+
+export function routeId(route: RouteFact): string {
+  return NODE_PREFIX.route + route.method + " " + route.path;
+}
+
+export function pageId(path: string): string {
+  return NODE_PREFIX.page + path;
+}
+
+export function workflowId(name: string): string {
+  return NODE_PREFIX.workflow + name;
+}

package/src/graph.ts

@@ -0,0 +1,190 @@
+import type {
+  GraphNode,
+  PageFact,
+  PageNodeData,
+  ProjectGraph,
+  RelationFact,
+  RouteFact,
+  RouteNodeData,
+  ScreenFacts,
+  TableFact,
+  TableNodeData,
+  ViewFact,
+  ViewNodeData,
+  WorkflowFact,
+  WorkflowNodeData,
+} from "./types.ts";
+import { pageId, routeId, tableId, viewId, workflowId } from "./graph-ids.ts";
+import { collectEdges } from "./graph-edges.ts";
+
+export interface GraphInput {
+  readonly routes: readonly RouteFact[];
+  readonly tables: readonly TableFact[];
+  readonly relations: readonly RelationFact[];
+  readonly pages: readonly PageFact[];
+  /** Declarative views (D-097/D-098): nodes plus view-base edges since D-160. */
+  readonly views: readonly ViewFact[];
+  /** Route paths, bounded page previews and explicit page links. */
+  readonly screens?: ScreenFacts;
+  /** Workflow definitions read from `server/workflows/**` (D-135 W3). */
+  readonly workflows?: readonly WorkflowFact[];
+}
+
+function tableNode(table: TableFact): GraphNode {
+  const data: TableNodeData = {
+    kind: "table",
+    table: table.name,
+    columns: table.columns,
+    rlsEnabled: table.rlsEnabled,
+    scope: table.scope,
+    framework: table.source.file.startsWith("node_modules/"),
+    unknown:
+      table.unknown.length > 0 ||
+      table.columns.some((column) => column.unknown.length > 0) ||
+      table.policies.some((policy) => policy.unknown.length > 0),
+  };
+  return {
+    id: tableId(table.name),
+    kind: "table",
+    label: table.name,
+    sourceFile: table.source.file,
+    data,
+  };
+}
+
+function viewNode(view: ViewFact): GraphNode {
+  const data: ViewNodeData = {
+    kind: "view",
+    view: view.name,
+    tables: view.tables,
+    permission: view.permission,
+    access: view.access,
+    unknown: view.unknown.length > 0 || view.access === null,
+  };
+  return {
+    id: viewId(view.name),
+    kind: "view",
+    label: view.name,
+    sourceFile: view.source.file,
+    data,
+  };
+}
+
+function workflowNode(workflow: WorkflowFact): GraphNode {
+  const data: WorkflowNodeData = {
+    kind: "workflow",
+    name: workflow.name,
+    steps: workflow.steps.map((step) => ({
+      index: step.index,
+      kind: step.kind,
+      name: step.name,
+      permission: step.permission,
+      onRejectStep: step.onRejectStep,
+    })),
+    unknown: workflow.unknown.length > 0 || workflow.steps.some((step) => step.name === null),
+  };
+  return {
+    id: workflowId(workflow.name),
+    kind: "workflow",
+    label: workflow.name,
+    sourceFile: workflow.sourceFile,
+    data,
+  };
+}
+
+function routeNode(route: RouteFact, id: string): GraphNode {
+  const data: RouteNodeData = {
+    kind: "route",
+    method: route.method,
+    path: route.path,
+    permission: route.permission ?? [],
+    wrapper: route.wrapper,
+    input: route.input,
+    dbTables: route.dbTables ?? [],
+    dbColumns: route.dbColumns ?? [],
+    elevations: route.elevations,
+    description: route.description,
+    unknown:
+      route.unknown.length > 0 ||
+      route.wrapper === "unknown" ||
+      route.permission === null ||
+      route.dbTables === null,
+  };
+  return {
+    id,
+    kind: "route",
+    label: route.method + " " + route.path,
+    sourceFile: route.sourceFile,
+    data,
+  };
+}
+
+function pageNode(page: PageFact, id: string, screens: ScreenFacts): GraphNode {
+  const preview = screens.previews[page.path];
+  const data: PageNodeData = {
+    kind: "page",
+    pagePath: page.path,
+    pageKind: page.kind,
+    callCount: page.calls.length,
+    ...(preview === undefined ? {} : { routePaths: preview.routePaths, preview }),
+  };
+  return {
+    id,
+    kind: "page",
+    label: page.path,
+    sourceFile: page.path,
+    data,
+  };
+}
+
+function collectNodes(input: GraphInput): GraphNode[] {
+  const nodes: GraphNode[] = [];
+  const tableNames = new Set<string>();
+  for (const table of input.tables) {
+    if (tableNames.has(table.name)) continue;
+    tableNames.add(table.name);
+    nodes.push(tableNode(table));
+  }
+  const viewNames = new Set<string>();
+  for (const view of input.views) {
+    if (viewNames.has(view.name)) continue;
+    viewNames.add(view.name);
+    nodes.push(viewNode(view));
+  }
+  const routeIds = new Set<string>();
+  for (const route of input.routes) {
+    const id = routeId(route);
+    if (routeIds.has(id)) continue;
+    routeIds.add(id);
+    nodes.push(routeNode(route, id));
+  }
+  const pageIds = new Set<string>();
+  const screens = input.screens ?? { previews: {}, links: [] };
+  for (const page of input.pages) {
+    // The graph's page nodes are real pages only (the user's "pagine e basta"): components and
+    // lib files that happen to call an API stay analyzer facts, not boxes on the canvas.
+    if (page.kind !== "page") continue;
+    const id = pageId(page.path);
+    if (pageIds.has(id)) continue;
+    pageIds.add(id);
+    nodes.push(pageNode(page, id, screens));
+  }
+  const workflowIds = new Set<string>();
+  for (const workflow of input.workflows ?? []) {
+    const id = workflowId(workflow.name);
+    if (workflowIds.has(id)) continue;
+    workflowIds.add(id);
+    nodes.push(workflowNode(workflow));
+  }
+  return nodes;
+}
+
+/** Build the single project graph from facts. Ids and ordering are stable across runs. */
+export function buildProjectGraph(input: GraphInput): ProjectGraph {
+  const nodes = collectNodes(input);
+  const nodeIds = new Set(nodes.map((node) => node.id));
+  const edges = collectEdges(input, nodeIds);
+  nodes.sort((left, right) => left.id.localeCompare(right.id));
+  edges.sort((left, right) => left.id.localeCompare(right.id));
+  return { nodes, edges };
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @facilis.dev/analyze — static facts for the Facilis project DSL.
+ *
+ * Zero build-time execution: the caller supplies a file map and an injected parser; the
+ * analyzer interprets the declared DSL (routes, config, Drizzle schema, relations, pages).
+ * The Node parser adapter lives on the `@facilis.dev/analyze/node` subpath so the main entry
+ * stays browser-safe.
+ */
+export { analyzeProject, DEFAULT_TRANSPORT } from "./analyze.ts";
+export type { AnalyzeInput } from "./analyze.ts";
+export { buildProjectGraph } from "./graph.ts";
+export type { GraphInput } from "./graph.ts";
+export { ROUTE_DESCRIPTION_MAX_CHARS } from "./passes/route-description.ts";
+export { createModuleGraph } from "./module-graph.ts";
+export type { Binding, ModuleGraph, ProjectFile } from "./module-graph.ts";
+export { createPathResolver, normalizePath } from "./path-resolver.ts";
+export type { PathAlias } from "./path-resolver.ts";
+export type { Parser, ParseError, ParsedModule } from "./parser.ts";
+export { diagnostic, error, info, warning } from "./diagnostics.ts";
+export { computeRevision } from "./revision.ts";
+export type { TransportSpec } from "./passes/clients.ts";
+// Job facts live in types-jobs.ts (the 300-line split of types.ts), so export them here.
+export type { JobFact, JobRelationsFact } from "./types-jobs.ts";
+export type * from "./types.ts";

package/src/json.ts

@@ -0,0 +1,34 @@
+import { isAstNode } from "./ast/node.ts";
+
+/** Parse a JSON file from the project file map; null when absent or malformed. */
+export function readJson(files: ReadonlyMap<string, string>, path: string): unknown {
+  const source = files.get(path);
+  if (source === undefined) return null;
+  try {
+    return JSON.parse(source) as unknown;
+  } catch {
+    return null;
+  }
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Module source extensions the analyzer can parse. */
+export const SOURCE_EXTENSIONS = [
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".mts",
+  ".cts",
+] as const;
+
+export function isSourceFile(path: string): boolean {
+  return SOURCE_EXTENSIONS.some((extension) => path.endsWith(extension));
+}
+
+export { isAstNode };

package/src/module-graph.ts

@@ -0,0 +1,117 @@
+import { isSourceFile, readJson as parseJson } from "./json.ts";
+import { parseModuleInfo, type ModuleInfo } from "./module-info.ts";
+import { createPathResolver, normalizePath, type PathAlias } from "./path-resolver.ts";
+import type { ParseError, Parser } from "./parser.ts";
+import type { AstNode } from "./ast/node.ts";
+
+export interface ProjectFile {
+  readonly path: string;
+  readonly source: string;
+  readonly program: AstNode;
+  readonly errors: readonly ParseError[];
+  readonly module: ModuleInfo;
+}
+
+export interface Binding {
+  readonly file: string;
+  readonly name: string;
+}
+
+export interface ModuleGraph {
+  readonly files: ReadonlyMap<string, ProjectFile>;
+  /** Every input file (including JSON/tsconfig/package.json), path -> source. */
+  readonly allFiles: ReadonlyMap<string, string>;
+  readonly root: string;
+  file(path: string): ProjectFile | undefined;
+  resolve(from: string, specifier: string): string | null;
+  resolveBinding(file: string, local: string): Binding | null;
+  resolveExport(file: string, name: string): Binding | null;
+  readJson(path: string): unknown;
+}
+
+export interface ModuleGraphInput {
+  readonly files: ReadonlyMap<string, string>;
+  readonly parser: Parser;
+  readonly root?: string;
+  readonly aliases?: readonly PathAlias[];
+}
+
+export function createModuleGraph(input: ModuleGraphInput): ModuleGraph {
+  const root = normalizePath(input.root ?? "");
+  const sources = new Map<string, string>();
+  const files = new Map<string, ProjectFile>();
+  for (const [rawPath, source] of input.files) {
+    const path = normalizePath(rawPath);
+    sources.set(path, source);
+    if (!isSourceFile(path)) continue;
+    const parsed = input.parser.parse(path, source);
+    files.set(path, {
+      path,
+      source,
+      program: parsed.program,
+      errors: parsed.errors,
+      module: parseModuleInfo(path, source, parsed.program),
+    });
+  }
+
+  const resolver = createPathResolver({
+    exists: (path) => sources.has(path),
+    readJson: (path) => parseJson(sources, path),
+    root,
+    ...(input.aliases === undefined ? {} : { aliases: input.aliases }),
+  });
+
+  const resolveExport = (file: string, name: string, seen = new Set<string>()): Binding | null => {
+    const key = file + "#" + name;
+    if (seen.has(key)) return null;
+    seen.add(key);
+    const module = files.get(file);
+    if (module === undefined) return null;
+    const direct = module.module.exports.find((entry) => entry.exported === name);
+    if (direct !== undefined) {
+      if (direct.source !== null) {
+        const target = resolver.resolve(file, direct.source);
+        if (target === null) return null;
+        if (direct.kind === "all") return resolveExport(target, "*", seen);
+        return resolveExport(target, direct.imported ?? name, seen);
+      }
+      if (direct.local !== null) return resolveBinding(file, direct.local, seen);
+      return { file, name };
+    }
+    for (const entry of module.module.exports) {
+      if (entry.kind !== "all" || entry.source === null) continue;
+      const target = resolver.resolve(file, entry.source);
+      if (target !== null) {
+        const found = resolveExport(target, name, new Set(seen));
+        if (found !== null) return found;
+      }
+    }
+    return null;
+  };
+
+  const resolveBinding = (
+    file: string,
+    local: string,
+    seen = new Set<string>(),
+  ): Binding | null => {
+    const module = files.get(file);
+    if (module === undefined) return null;
+    const imported = module.module.imports.find((entry) => entry.local === local);
+    if (imported === undefined) return { file, name: local };
+    if (imported.kind === "namespace") return null;
+    const target = resolver.resolve(file, imported.specifier);
+    if (target === null) return null;
+    return resolveExport(target, imported.imported ?? "default", new Set(seen));
+  };
+
+  return {
+    files,
+    allFiles: sources,
+    root,
+    file: (path) => files.get(normalizePath(path)),
+    resolve: resolver.resolve,
+    resolveBinding: (file, local) => resolveBinding(normalizePath(file), local),
+    resolveExport: (file, name) => resolveExport(normalizePath(file), name),
+    readJson: (path) => parseJson(sources, normalizePath(path)),
+  };
+}