@facilis.dev/analyze 0.0.0-stage → 0.1.1

package/src/path-resolver.ts

@@ -0,0 +1,146 @@
+/** Project-relative path handling and module specifier resolution (no Node APIs). */
+
+export interface PathAlias {
+  readonly prefix: string;
+  readonly target: string;
+}
+
+export interface PathResolverInput {
+  readonly exists: (path: string) => boolean;
+  readonly readJson: (path: string) => unknown;
+  readonly root: string;
+  readonly aliases?: readonly PathAlias[];
+}
+
+export interface PathResolver {
+  resolve(from: string, specifier: string): string | null;
+  tryFile(path: string): string | null;
+}
+
+export const SOURCE_EXTENSIONS = [
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".mts",
+  ".cts",
+] as const;
+
+export function normalizePath(path: string): string {
+  const parts = path.replace(/\\/g, "/").split("/");
+  const out: string[] = [];
+  for (const part of parts) {
+    if (part === "" || part === ".") continue;
+    if (part === "..") {
+      out.pop();
+      continue;
+    }
+    out.push(part);
+  }
+  return out.join("/");
+}
+
+export function dirname(path: string): string {
+  const index = path.lastIndexOf("/");
+  return index === -1 ? "" : path.slice(0, index);
+}
+
+export function joinPath(base: string, relative: string): string {
+  return normalizePath(base.length === 0 ? relative : base + "/" + relative);
+}
+
+function packageSpecifier(specifier: string): { pkg: string; subpath: string } {
+  const parts = specifier.split("/");
+  if (specifier.startsWith("@")) {
+    return { pkg: parts.slice(0, 2).join("/"), subpath: parts.slice(2).join("/") };
+  }
+  return { pkg: parts[0] ?? specifier, subpath: parts.slice(1).join("/") };
+}
+
+function exportTargets(exports: unknown): string[] {
+  if (typeof exports === "string") return [exports];
+  if (Array.isArray(exports)) return exports.flatMap(exportTargets);
+  if (typeof exports !== "object" || exports === null) return [];
+  const record = exports as Record<string, unknown>;
+  const out: string[] = [];
+  for (const key of ["import", "default", "browser", "node"]) {
+    if (key in record) out.push(...exportTargets(record[key]));
+  }
+  return out;
+}
+
+export function createPathResolver(input: PathResolverInput): PathResolver {
+  const root = normalizePath(input.root);
+  const aliases: PathAlias[] = [
+    { prefix: "~/", target: root },
+    { prefix: "~", target: root },
+    ...(input.aliases ?? []),
+  ];
+
+  const tryFile = (path: string): string | null => {
+    if (input.exists(path)) return path;
+    for (const extension of SOURCE_EXTENSIONS) {
+      if (input.exists(path + extension)) return path + extension;
+    }
+    for (const extension of SOURCE_EXTENSIONS) {
+      const index = joinPath(path, "index" + extension);
+      if (input.exists(index)) return index;
+    }
+    return null;
+  };
+
+  const resolvePackage = (specifier: string): string | null => {
+    const { pkg, subpath } = packageSpecifier(specifier);
+    const prefix = "node_modules/" + pkg;
+    const packageJson = input.readJson(prefix + "/package.json");
+    if (typeof packageJson !== "object" || packageJson === null) return null;
+    const record = packageJson as Record<string, unknown>;
+    if (subpath.length > 0) {
+      const exports = record["exports"];
+      if (typeof exports === "object" && exports !== null) {
+        const entry = (exports as Record<string, unknown>)["./" + subpath];
+        for (const target of exportTargets(entry)) {
+          const resolved = tryFile(joinPath(prefix, target));
+          if (resolved !== null) return resolved;
+        }
+      }
+      return tryFile(joinPath(prefix, subpath));
+    }
+    const exports = record["exports"];
+    if (typeof exports === "object" && exports !== null) {
+      const entry = (exports as Record<string, unknown>)["."];
+      for (const target of exportTargets(entry)) {
+        const resolved = tryFile(joinPath(prefix, target));
+        if (resolved !== null) return resolved;
+      }
+    }
+    for (const target of ["main", "module"]) {
+      const value = record[target];
+      if (typeof value === "string") {
+        const resolved = tryFile(joinPath(prefix, value));
+        if (resolved !== null) return resolved;
+      }
+    }
+    return tryFile(joinPath(prefix, "src/index.ts")) ?? tryFile(joinPath(prefix, "index.ts"));
+  };
+
+  const resolve = (from: string, rawSpecifier: string): string | null => {
+    const specifier = rawSpecifier.trim();
+    if (specifier.length === 0) return null;
+    for (const alias of aliases) {
+      if (specifier === alias.prefix || specifier.startsWith(alias.prefix)) {
+        const rest = specifier.slice(alias.prefix.length);
+        const target = alias.target.length === 0 ? rest : joinPath(alias.target, rest);
+        const resolved = tryFile(target);
+        if (resolved !== null) return resolved;
+      }
+    }
+    if (specifier.startsWith(".")) return tryFile(joinPath(dirname(from), specifier));
+    if (specifier.startsWith("/")) return tryFile(normalizePath(specifier));
+    return resolvePackage(specifier);
+  };
+
+  return { resolve, tryFile };
+}

package/src/revision.ts

@@ -0,0 +1,25 @@
+import { normalizePath } from "./path-resolver.ts";
+
+/** Deterministic, browser-safe revision of the analyzed file set. */
+export function computeRevision(files: ReadonlyMap<string, string>): string {
+  const entries = [...files]
+    .map(([path, source]) => [normalizePath(path), source] as const)
+    .toSorted(([left], [right]) => left.localeCompare(right));
+  let hash = 0x811c9dc5;
+  for (const [path, source] of entries) {
+    hash = mix(hash, path);
+    hash = mix(hash, "\u0000");
+    hash = mix(hash, source);
+    hash = mix(hash, "\u0001");
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+function mix(hash: number, value: string): number {
+  let next = hash;
+  for (let index = 0; index < value.length; index += 1) {
+    next ^= value.charCodeAt(index);
+    next = Math.imul(next, 0x01000193) >>> 0;
+  }
+  return next;
+}

package/src/source.ts

@@ -0,0 +1,15 @@
+import type { SourceRef } from "./types.ts";
+
+/** 1-based line number of a source offset. */
+export function lineOf(source: string, offset: number): number {
+  let line = 1;
+  const end = Math.min(Math.max(offset, 0), source.length);
+  for (let index = 0; index < end; index += 1) {
+    if (source.charCodeAt(index) === 10) line += 1;
+  }
+  return line;
+}
+
+export function sourceRef(file: string, source: string, offset: number): SourceRef {
+  return { file, line: lineOf(source, offset) };
+}

package/src/static-eval.ts

@@ -0,0 +1,242 @@
+import {
+  asNode,
+  identifierName,
+  literalString,
+  memberName,
+  nodeArray,
+  objectEntries,
+  propertyName,
+  propertyValue,
+  unwrapExpression,
+  type AstNode,
+} from "./ast/node.ts";
+import { defaultExportDeclaration, localInitializer } from "./module-info.ts";
+import type { ModuleGraph } from "./module-graph.ts";
+
+export type StaticEvaluation =
+  { readonly ok: true; readonly value: unknown } | { readonly ok: false; readonly reason: string };
+
+export interface StaticContext {
+  readonly graph: ModuleGraph;
+  readonly file: string;
+}
+
+const MAX_DEPTH = 16;
+
+function fail(reason: string): StaticEvaluation {
+  return { ok: false, reason };
+}
+
+function fromValue(value: unknown): StaticEvaluation {
+  return { ok: true, value };
+}
+
+/**
+ * Evaluate the static subset (docs/findings/ast-dsl-contract.md §4): literals, arrays,
+ * objects, templates without dynamic parts, same-file consts and one-hop project imports.
+ * Never executes code; anything else fails and the caller records an unknown fact.
+ */
+export function evaluateStatic(
+  node: AstNode | undefined,
+  context: StaticContext,
+  depth = 0,
+): StaticEvaluation {
+  if (node === undefined) return fail("missing value");
+  if (depth > MAX_DEPTH) return fail("static evaluation is too deep or cyclic");
+  const unwrapped = unwrapExpression(node) ?? node;
+  switch (unwrapped.type) {
+    case "Literal":
+      return "value" in unwrapped ? fromValue(unwrapped.value) : fail("unsupported literal");
+    case "TemplateLiteral":
+      return evaluateTemplate(unwrapped, context, depth);
+    case "ArrayExpression":
+      return evaluateArray(unwrapped, context, depth);
+    case "ObjectExpression":
+      return evaluateObject(unwrapped, context, depth);
+    case "UnaryExpression":
+      return evaluateUnary(unwrapped, context, depth);
+    case "BinaryExpression":
+      return evaluateBinary(unwrapped, context, depth);
+    case "MemberExpression":
+      return evaluateMember(unwrapped, context, depth);
+    case "Identifier":
+      return evaluateIdentifier(unwrapped, context, depth);
+    default:
+      return fail('"' + unwrapped.type + '" is not in the static subset');
+  }
+}
+
+function evaluateIdentifier(
+  node: AstNode,
+  context: StaticContext,
+  depth: number,
+): StaticEvaluation {
+  const name = identifierName(node);
+  if (name === undefined) return fail("missing identifier name");
+  if (name === "undefined") return fromValue(undefined);
+  const current = context.graph.file(context.file);
+  if (current === undefined) return fail("unknown file " + context.file);
+  const local = localInitializer(current.program, name);
+  if (local !== undefined) return evaluateStatic(local, context, depth + 1);
+  const binding = context.graph.resolveBinding(context.file, name);
+  if (binding === null) return fail('cannot resolve "' + name + '" statically');
+  const target = context.graph.file(binding.file);
+  if (target === undefined) return fail("unknown module " + binding.file);
+  if (binding.name === "default") {
+    const declaration = defaultExportDeclaration(target.program);
+    if (declaration === undefined) return fail("module has no default export");
+    return evaluateStatic(declaration, { graph: context.graph, file: target.path }, depth + 1);
+  }
+  const initializer = localInitializer(target.program, binding.name);
+  if (initializer === undefined) return fail('cannot resolve "' + binding.name + '" statically');
+  return evaluateStatic(initializer, { graph: context.graph, file: target.path }, depth + 1);
+}
+
+function evaluateTemplate(node: AstNode, context: StaticContext, depth: number): StaticEvaluation {
+  const quasis = nodeArray(node, "quasis");
+  const expressions = nodeArray(node, "expressions");
+  let out = "";
+  for (const [index, quasi] of quasis.entries()) {
+    // TemplateElement.value is a plain { raw, cooked } record, not an AST node.
+    const value = quasi?.value as { cooked?: unknown } | undefined;
+    const cooked = value?.cooked;
+    out += typeof cooked === "string" ? cooked : "";
+    const expression = expressions[index];
+    if (expression === undefined) continue;
+    const evaluated = evaluateStatic(expression, context, depth + 1);
+    if (!evaluated.ok) return evaluated;
+    if (
+      typeof evaluated.value !== "string" &&
+      typeof evaluated.value !== "number" &&
+      typeof evaluated.value !== "boolean"
+    ) {
+      return fail("template interpolation is not a primitive");
+    }
+    out += String(evaluated.value);
+  }
+  return fromValue(out);
+}
+
+function evaluateArray(node: AstNode, context: StaticContext, depth: number): StaticEvaluation {
+  const out: unknown[] = [];
+  for (const element of nodeArray(node, "elements")) {
+    const evaluated = evaluateStatic(element, context, depth + 1);
+    if (!evaluated.ok) return evaluated;
+    out.push(evaluated.value);
+  }
+  return fromValue(out);
+}
+
+function evaluateObject(node: AstNode, context: StaticContext, depth: number): StaticEvaluation {
+  const out: Record<string, unknown> = {};
+  for (const entry of objectEntries(node)) {
+    if (entry.type === "SpreadElement") {
+      const argument = asNode(entry.argument);
+      const spread = evaluateStatic(argument, context, depth + 1);
+      if (!spread.ok) return spread;
+      if (typeof spread.value !== "object" || spread.value === null) {
+        return fail("object spread is not an object literal");
+      }
+      Object.assign(out, spread.value);
+      continue;
+    }
+    const key = propertyName(entry);
+    if (key === undefined) return fail("computed object key is not in the static subset");
+    const evaluated = evaluateStatic(propertyValue(entry), context, depth + 1);
+    if (!evaluated.ok) return evaluated;
+    out[key] = evaluated.value;
+  }
+  return fromValue(out);
+}
+
+function evaluateUnary(node: AstNode, context: StaticContext, depth: number): StaticEvaluation {
+  const argument = asNode(node.argument);
+  const evaluated = evaluateStatic(argument, context, depth + 1);
+  if (!evaluated.ok) return evaluated;
+  if (node.operator === "-" && typeof evaluated.value === "number") {
+    return fromValue(-evaluated.value);
+  }
+  if (node.operator === "!" && typeof evaluated.value === "boolean") {
+    return fromValue(!evaluated.value);
+  }
+  return fail("unsupported unary expression");
+}
+
+const NUMERIC_OPERATORS = new Set(["+", "-", "*", "/", "%"]);
+
+function evaluateBinary(node: AstNode, context: StaticContext, depth: number): StaticEvaluation {
+  const operator = node.operator;
+  if (typeof operator !== "string" || !NUMERIC_OPERATORS.has(operator)) {
+    return fail("unsupported binary expression");
+  }
+  const left = evaluateStatic(asNode(node.left), context, depth + 1);
+  if (!left.ok) return left;
+  const right = evaluateStatic(asNode(node.right), context, depth + 1);
+  if (!right.ok) return right;
+  if (operator === "+" && (typeof left.value === "string" || typeof right.value === "string")) {
+    if (typeof left.value !== "string" && typeof left.value !== "number") {
+      return fail("binary + operands are not primitives");
+    }
+    if (typeof right.value !== "string" && typeof right.value !== "number") {
+      return fail("binary + operands are not primitives");
+    }
+    return fromValue(String(left.value) + String(right.value));
+  }
+  if (typeof left.value !== "number" || typeof right.value !== "number") {
+    return fail("binary " + operator + " operands are not numbers");
+  }
+  switch (operator) {
+    case "+":
+      return fromValue(left.value + right.value);
+    case "-":
+      return fromValue(left.value - right.value);
+    case "*":
+      return fromValue(left.value * right.value);
+    case "/":
+      return fromValue(left.value / right.value);
+    case "%":
+      return fromValue(left.value % right.value);
+    default:
+      return fail("unsupported binary expression");
+  }
+}
+
+function evaluateMember(node: AstNode, context: StaticContext, depth: number): StaticEvaluation {
+  const name = memberName(node);
+  if (name === undefined) return fail("unsupported member expression");
+  const object = evaluateStatic(asNode(node.object), context, depth + 1);
+  if (!object.ok) return object;
+  if (typeof object.value !== "object" || object.value === null) {
+    return fail("member access on a non-object");
+  }
+  const record = object.value as Record<string, unknown>;
+  return Object.hasOwn(record, name) ? fromValue(record[name]) : fail("missing property " + name);
+}
+
+/** Convenience: a string or undefined, with the failure reason. */
+export function staticString(
+  node: AstNode | undefined,
+  context: StaticContext,
+): { ok: true; value: string } | { ok: false; reason: string } {
+  const evaluated = evaluateStatic(node, context);
+  if (!evaluated.ok) return evaluated;
+  return typeof evaluated.value === "string"
+    ? { ok: true, value: evaluated.value }
+    : { ok: false, reason: "expected a string literal" };
+}
+
+/** Convenience: a string[] or undefined, with the failure reason. */
+export function staticStringArray(
+  node: AstNode | undefined,
+  context: StaticContext,
+): { ok: true; value: string[] } | { ok: false; reason: string } {
+  const evaluated = evaluateStatic(node, context);
+  if (!evaluated.ok) return evaluated;
+  if (!Array.isArray(evaluated.value)) return { ok: false, reason: "expected a string[] literal" };
+  if (!evaluated.value.every((item): item is string => typeof item === "string")) {
+    return { ok: false, reason: "expected a string[] literal" };
+  }
+  return { ok: true, value: [...evaluated.value] };
+}
+
+export { literalString };

package/src/types-graph.ts

@@ -0,0 +1,176 @@
+// 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;
+}
+
+/**
+ * One policy as the graph names it (D-177): the card needs the grant/gate distinction, while the
+ * command and source stay in the inspector's facts.
+ */
+export interface TablePolicyNodeFact {
+  readonly name: string;
+  readonly restrictive: boolean;
+}
+
+export interface TableNodeData {
+  readonly kind: "table";
+  readonly table: string;
+  readonly columns: readonly ColumnFact[];
+  readonly rlsEnabled: boolean;
+  readonly scope: ScopeFact | null;
+  /** The declared policy set, in declaration order (D-177). */
+  readonly policies: readonly TablePolicyNodeFact[];
+  /**
+   * 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;
+  /** Direct literal text child, trimmed and whitespace-collapsed; absent when none. */
+  readonly text?: string;
+  /** i18n key when that text child is a `t("key")` call (D-043); absent otherwise. */
+  readonly tKey?: string;
+}
+
+/** 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,
+};