@facilis.dev/ai 0.0.0-stage → 0.1.1

package/src/rules/imports.ts

@@ -0,0 +1,227 @@
+/**
+ * Rules 9 `no-raw-db-access` and 12 `import-resolves` (SPEC §9.3).
+ *
+ * Rule 9 keeps raw database clients inside `@facilis.dev/db` (invariant 5); drizzle operators
+ * and `drizzle-orm/pg-core` are the schema DSL and stay allowed. Rule 12 checks that every
+ * module reference resolves against the effective file set, the project's aliases and the
+ * packages package.json declares — no filesystem, no node_modules walk.
+ *
+ * Both read the analyzer's ImportFacts, so static imports, re-exports, dynamic imports and
+ * `require()` share the same AST truth.
+ */
+
+import type { EffectiveState } from "../overlay.ts";
+import { normalizeProjectPath } from "../paths.ts";
+import type { ImportAlias, ImportFact, PatchContext, ValidationError } from "../types.ts";
+
+const RAW_DRIVER =
+  /^drizzle-orm\/(?:pglite|node-postgres|postgres-js|bun-sqlite|neon|vercel-postgres|aws-data-api|libsql|expo-sqlite|d1|op-sqlite|singlestore|tidb-serverless)$/;
+const RAW_CLIENTS = new Set(["@electric-sql/pglite", "postgres", "pg"]);
+
+const NODE_BUILTINS = new Set([
+  "assert",
+  "async_hooks",
+  "buffer",
+  "child_process",
+  "cluster",
+  "console",
+  "constants",
+  "crypto",
+  "dgram",
+  "diagnostics_channel",
+  "dns",
+  "domain",
+  "events",
+  "fs",
+  "http",
+  "http2",
+  "https",
+  "inspector",
+  "module",
+  "net",
+  "os",
+  "path",
+  "perf_hooks",
+  "process",
+  "punycode",
+  "querystring",
+  "readline",
+  "repl",
+  "stream",
+  "string_decoder",
+  "sys",
+  "timers",
+  "tls",
+  "trace_events",
+  "tty",
+  "url",
+  "util",
+  "v8",
+  "vm",
+  "wasi",
+  "worker_threads",
+  "zlib",
+]);
+
+const RESOLVABLE_EXTENSIONS = [
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".json",
+  ".css",
+  ".svg",
+];
+const HAS_EXTENSION = /\.[A-Za-z0-9]+$/;
+
+function error(
+  rule: string,
+  file: string,
+  message: string,
+  fix_hint: string,
+  line?: number,
+): ValidationError {
+  return {
+    rule,
+    severity: "error",
+    file,
+    message,
+    fix_hint,
+    ...(line === undefined ? {} : { line }),
+  };
+}
+
+/** Imports deduped per statement: a named-import clause produces one fact per name. */
+function statementImports(imports: readonly ImportFact[]): ImportFact[] {
+  const seen = new Set<string>();
+  const unique: ImportFact[] = [];
+  for (const imported of imports) {
+    const key = imported.specifier + "\u0000" + imported.source.line;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    unique.push(imported);
+  }
+  return unique;
+}
+
+export function rawDbAccessErrors(state: EffectiveState): ValidationError[] {
+  const errors: ValidationError[] = [];
+  for (const facts of state.patchedFileFacts) {
+    const imports = statementImports(facts.imports);
+    for (const imported of imports) {
+      if (!RAW_DRIVER.test(imported.specifier) && !RAW_CLIENTS.has(imported.specifier)) continue;
+      errors.push(
+        error(
+          "no-raw-db-access",
+          facts.path,
+          'Importing "' + imported.specifier + '" is a raw database client outside @facilis.dev/db.',
+          "Go through the policy-scoped db the handler receives (invariant 5).",
+          imported.source.line,
+        ),
+      );
+    }
+    const rawDrizzleImport = imports.find((imported) => imported.specifier === "drizzle-orm");
+    if (rawDrizzleImport !== undefined && facts.calls.some((call) => call.name === "drizzle")) {
+      errors.push(
+        error(
+          "no-raw-db-access",
+          facts.path,
+          "Constructing a raw drizzle() client is not allowed outside @facilis.dev/db.",
+          "Use the policy-scoped db from the handler context; import operators from drizzle-orm instead (invariant 5).",
+          rawDrizzleImport.source.line,
+        ),
+      );
+    }
+  }
+  return errors;
+}
+
+function fileExists(files: ReadonlySet<string>, base: string): boolean {
+  const target = normalizeProjectPath(base);
+  if (target.length === 0) return false;
+  if (files.has(target)) return true;
+  if (HAS_EXTENSION.test(target)) return false;
+  for (const extension of RESOLVABLE_EXTENSIONS) {
+    if (files.has(target + extension)) return true;
+    if (files.has(target + "/index" + extension)) return true;
+  }
+  return false;
+}
+
+function relativeBase(fromPath: string, specifier: string): string {
+  const directory = fromPath.split("/").slice(0, -1);
+  const segments = [...directory, ...specifier.split("/")];
+  const resolved: string[] = [];
+  for (const segment of segments) {
+    if (segment.length === 0 || segment === ".") continue;
+    if (segment === "..") {
+      resolved.pop();
+      continue;
+    }
+    resolved.push(segment);
+  }
+  return resolved.join("/");
+}
+
+function aliasBase(specifier: string, aliases: readonly ImportAlias[]): string | null {
+  for (const alias of aliases) {
+    if (!specifier.startsWith(alias.prefix)) continue;
+    return normalizeProjectPath(alias.target + specifier.slice(alias.prefix.length));
+  }
+  return null;
+}
+
+function stripQuery(specifier: string): string {
+  const cut = specifier.search(/[?#]/);
+  return cut === -1 ? specifier : specifier.slice(0, cut);
+}
+
+function packageNameOf(specifier: string): string {
+  const parts = specifier.split("/");
+  if (specifier.startsWith("@")) return parts.slice(0, 2).join("/");
+  return parts[0] ?? specifier;
+}
+
+export function importResolveErrors(
+  state: EffectiveState,
+  context: PatchContext,
+): ValidationError[] {
+  const errors: ValidationError[] = [];
+  for (const facts of state.patchedFileFacts) {
+    for (const imported of statementImports(facts.imports)) {
+      const specifier = stripQuery(imported.specifier);
+      if (specifier.length === 0) continue;
+      if (specifier.startsWith("node:") || NODE_BUILTINS.has(specifier)) continue;
+      if (/^[a-z][a-z0-9+.-]*:/i.test(specifier)) continue;
+      const relative =
+        specifier.startsWith("./") || specifier.startsWith("../") || specifier.startsWith("/");
+      if (relative) {
+        const base = specifier.startsWith("/")
+          ? specifier.replace(/^\/+/, "")
+          : relativeBase(facts.path, specifier);
+        if (fileExists(state.files, base)) continue;
+      } else {
+        const alias = aliasBase(specifier, context.aliases);
+        if (alias !== null) {
+          if (fileExists(state.files, alias)) continue;
+        } else if (context.packages.includes(packageNameOf(specifier))) {
+          continue;
+        }
+      }
+      errors.push(
+        error(
+          "import-resolves",
+          facts.path,
+          'Import "' + imported.specifier + '" does not resolve.',
+          relative
+            ? "Point the import at a file that exists (or is created by this patch)."
+            : "Use a package declared in package.json; new dependencies need user approval.",
+          imported.source.line,
+        ),
+      );
+    }
+  }
+  return errors;
+}

package/src/rules/job-relations.ts

@@ -0,0 +1,126 @@
+/**
+ * Rule 19 `job-table-declared` (SPEC §9.3, D-157 applied to jobs): a job's `dbTables` is an
+ * applied declaration.
+ *
+ * A job's `run(ctx)` always receives the system-scoped client (D-107), so its usage has no
+ * elevation dimension: every relation it reaches — tables and views — must be declared,
+ * following project-local helper calls, and a missing or unreadable declaration fails closed.
+ * The rule covers **all** effective jobs whose usage facts exist, not only the patched ones: a
+ * patch that edits a shared helper changes what untouched jobs touch, and must not bypass the
+ * declaration.
+ *
+ * Errors: undeclared, unresolved/dynamic relation, `db.execute` without `rawSql: true` and a
+ * declaration that cannot be read. Warning: declared but unused (suppressed when usage is
+ * opaque or raw SQL is present, where the declaration stays authoritative).
+ */
+
+import type { EffectiveState } from "../overlay.ts";
+import type { JobRelationsFact, ValidationError } from "../types.ts";
+
+function lineOf(source: { readonly line: number } | undefined): number | undefined {
+  return source?.line;
+}
+
+function error(
+  file: string,
+  message: string,
+  fixHint: string,
+  line: number | undefined,
+): ValidationError {
+  return {
+    rule: "job-table-declared",
+    severity: "error",
+    file,
+    message,
+    fix_hint: fixHint,
+    ...(line === undefined ? {} : { line }),
+  };
+}
+
+function unusedWarning(job: { readonly sourceFile: string }, name: string): ValidationError {
+  return {
+    rule: "job-table-declared",
+    severity: "warning",
+    file: job.sourceFile,
+    message: 'dbTables declares "' + name + '" but the job never uses it.',
+    fix_hint:
+      'Remove "' + name + '" from dbTables, or use it: the declaration is enforced (D-157).',
+  };
+}
+
+/** Opaque usage or raw SQL keeps the declaration authoritative instead of warning. */
+function unusedSuppressed(usage: JobRelationsFact): boolean {
+  return usage.opaque || usage.rawSql.length > 0;
+}
+
+export interface JobTableDeclaredFindings {
+  readonly errors: ValidationError[];
+  readonly warnings: ValidationError[];
+}
+
+/** Rule 19 over the effective analysis (SPEC §9.3, D-157 applied to jobs). */
+export function jobTableDeclaredFindings(state: EffectiveState): JobTableDeclaredFindings {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationError[] = [];
+  for (const job of state.analysis.jobs) {
+    // A hand-built analysis may predate the fact: no usage facts, no check.
+    const usage: JobRelationsFact | undefined = state.analysis.jobRelations[job.name];
+    if (usage === undefined) continue;
+    const declared = job.dbTables === null ? null : new Set(job.dbTables);
+    if (declared === null) {
+      errors.push(
+        error(
+          job.sourceFile,
+          'Job "' + job.name + '" dbTables is missing or cannot be read statically.',
+          "Declare dbTables on defineJob({...}): every table or view the run body touches ([] means none).",
+          lineOf(job.source),
+        ),
+      );
+    } else {
+      for (const use of usage.used) {
+        if (declared.has(use.name)) continue;
+        errors.push(
+          error(
+            use.source.file,
+            'Relation "' + use.name + '" is used through the job db but not declared in dbTables.',
+            'Add "' +
+              use.name +
+              '" to dbTables (tables and views the run body touches), or stop using it.',
+            lineOf(use.source),
+          ),
+        );
+      }
+    }
+    for (const source of usage.unresolved) {
+      errors.push(
+        error(
+          source.file,
+          "A relation used through the job db cannot be resolved statically.",
+          "Use a table or view binding imported from db/ instead of a dynamic expression.",
+          lineOf(source),
+        ),
+      );
+    }
+    for (const source of usage.rawSql) {
+      if (job.rawSql === true) continue;
+      errors.push(
+        error(
+          source.file,
+          "db.execute() requires rawSql: true on the job definition.",
+          job.rawSql === null
+            ? "Declare rawSql: true (or false) statically, or use the query builder."
+            : "Add rawSql: true to defineJob({...}), or use the query builder.",
+          lineOf(source),
+        ),
+      );
+    }
+    if (declared !== null && !unusedSuppressed(usage)) {
+      const used = new Set(usage.used.map((use) => use.name));
+      for (const name of job.dbTables ?? []) {
+        if (used.has(name)) continue;
+        warnings.push(unusedWarning(job, name));
+      }
+    }
+  }
+  return { errors, warnings };
+}

package/src/rules/route-relations.ts

@@ -0,0 +1,162 @@
+/**
+ * Rule 18 `route-table-declared` (SPEC §9.3, D-157): `dbTables` is an applied declaration.
+ *
+ * Every relation a handler reaches through `ctx.db`, `ctx.sudo` or `ctx.system` — tables
+ * and views — must be declared, following project-local helper calls. The rule covers **all**
+ * effective routes whose usage facts exist, not only the patched ones: a patch that edits a
+ * shared helper changes what untouched routes touch, and must not bypass the declaration.
+ *
+ * Errors: undeclared, unresolved/dynamic relation, `db.execute` without `rawSql: true`,
+ * elevation use outside its `tables` option. Warning: declared but unused (suppressed when
+ * usage is opaque or raw SQL is present, where the declaration stays authoritative).
+ */
+
+import type { EffectiveState } from "../overlay.ts";
+import type { RouteRelationsFact, ValidationError } from "../types.ts";
+
+function lineOf(source: { readonly line: number } | undefined): number | undefined {
+  return source?.line;
+}
+
+function error(
+  file: string,
+  message: string,
+  fixHint: string,
+  line: number | undefined,
+): ValidationError {
+  return {
+    rule: "route-table-declared",
+    severity: "error",
+    file,
+    message,
+    fix_hint: fixHint,
+    ...(line === undefined ? {} : { line }),
+  };
+}
+
+function unusedWarning(route: { readonly sourceFile: string }, name: string): ValidationError {
+  return {
+    rule: "route-table-declared",
+    severity: "warning",
+    file: route.sourceFile,
+    message: 'dbTables declares "' + name + '" but the handler never uses it.',
+    fix_hint:
+      'Remove "' + name + '" from dbTables, or use it: the declaration is enforced (D-157).',
+  };
+}
+
+function usedNames(usage: RouteRelationsFact): ReadonlySet<string> {
+  const names = new Set(usage.used.map((use) => use.name));
+  for (const elevation of usage.elevations) {
+    for (const use of elevation.used) names.add(use.name);
+  }
+  return names;
+}
+
+/** Opaque usage or raw SQL keeps the declaration authoritative instead of warning. */
+function unusedSuppressed(usage: RouteRelationsFact): boolean {
+  return (
+    usage.opaque ||
+    usage.rawSql.length > 0 ||
+    usage.elevations.some((elevation) => elevation.opaque || elevation.tablesUnknown)
+  );
+}
+
+export interface RouteTableDeclaredFindings {
+  readonly errors: ValidationError[];
+  readonly warnings: ValidationError[];
+}
+
+/** Rule 18 over the effective analysis (SPEC §9.3, D-157). */
+export function routeTableDeclaredFindings(state: EffectiveState): RouteTableDeclaredFindings {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationError[] = [];
+  for (const route of state.analysis.routes) {
+    // A hand-built analysis may predate the fact (IDE snapshots): no usage facts, no check.
+    const usage: RouteRelationsFact | undefined = route.relations;
+    if (route.wrapper !== "valid" || usage === undefined) continue;
+    const declared = route.dbTables === null ? null : new Set(route.dbTables);
+    if (declared !== null) {
+      for (const use of usage.used) {
+        if (declared.has(use.name)) continue;
+        errors.push(
+          error(
+            use.source.file,
+            'Relation "' +
+              use.name +
+              '" is used through the route db but not declared in dbTables.',
+            'Add "' +
+              use.name +
+              '" to dbTables (tables and views the handler touches), or stop using it.',
+            lineOf(use.source),
+          ),
+        );
+      }
+      for (const elevation of usage.elevations) {
+        for (const use of elevation.used) {
+          if (declared.has(use.name)) continue;
+          errors.push(
+            error(
+              use.source.file,
+              'Relation "' +
+                use.name +
+                '" is used inside an elevation but not declared in dbTables.',
+              'Add "' + use.name + '" to dbTables and to the elevation tables option.',
+              lineOf(use.source),
+            ),
+          );
+        }
+      }
+    }
+    for (const source of usage.unresolved) {
+      errors.push(
+        error(
+          source.file,
+          "A relation used through the route db cannot be resolved statically.",
+          "Use a table or view binding imported from db/ instead of a dynamic expression.",
+          lineOf(source),
+        ),
+      );
+    }
+    for (const source of usage.rawSql) {
+      if (route.rawSql === true) continue;
+      errors.push(
+        error(
+          source.file,
+          "db.execute() requires rawSql: true on the route config.",
+          route.rawSql === null
+            ? "Declare rawSql: true (or false) statically, or use the query builder."
+            : "Add rawSql: true to the route config, or use the query builder.",
+          lineOf(source),
+        ),
+      );
+    }
+    for (const elevation of usage.elevations) {
+      if (elevation.tablesUnknown || elevation.opaque) continue;
+      const tables = new Set(elevation.tables);
+      for (const use of elevation.used) {
+        if (tables.has(use.name)) continue;
+        errors.push(
+          error(
+            use.source.file,
+            'Relation "' +
+              use.name +
+              '" is used inside the "' +
+              elevation.kind +
+              '" elevation but not declared in its tables option.',
+            'Add "' + use.name + '" to the elevation tables and to dbTables.',
+            lineOf(use.source),
+          ),
+        );
+      }
+    }
+    if (declared !== null && !unusedSuppressed(usage)) {
+      const used = usedNames(usage);
+      for (const name of route.dbTables ?? []) {
+        if (used.has(name)) continue;
+        warnings.push(unusedWarning(route, name));
+      }
+    }
+  }
+  return { errors, warnings };
+}

package/src/rules/routes-description.ts

@@ -0,0 +1,113 @@
+/**
+ * Rule 17 `route-description` (SPEC §9.3, D-129), a warning: the description is source
+ * documentation the project graph and the OpenAPI document show, so a missing, over-long or
+ * clearly stale one is worth fixing — but it must never stop a patch from applying.
+ *
+ * "Stale" is deliberately narrow: the text is unchanged while the route's contract changed
+ * in the same patch. Only then is the description demonstrably out of date rather than just
+ * terse, which a text check cannot tell. A route with an invalid wrapper is skipped because
+ * rule 2 already blocks it.
+ */
+
+import { ROUTE_DESCRIPTION_MAX_CHARS } from "@facilis.dev/analyze";
+
+import type { EffectiveState } from "../overlay.ts";
+import { normalizeProjectPath } from "../paths.ts";
+import type { RouteFact, ValidationError } from "../types.ts";
+import { patchedRoutes } from "./routes-security.ts";
+
+const RULE = "route-description";
+
+function warning(route: RouteFact, message: string, fix_hint: string): ValidationError {
+  return {
+    rule: RULE,
+    severity: "warning",
+    file: route.sourceFile,
+    message,
+    fix_hint,
+    line: route.source.line,
+  };
+}
+
+/** A contract list compared order-insensitively; null (unknown) stays distinct from []. */
+function stableList(values: readonly string[] | null): string | null {
+  return values === null ? null : [...values].sort().join("\u0000");
+}
+
+/**
+ * The contract fields D-129 says the description must cover. The lists are sorted because
+ * `permission`, `dbTables` and `dbColumns` are sets: reordering them changes no behaviour.
+ */
+function contractSignature(route: RouteFact): string {
+  return JSON.stringify([
+    route.wrapper,
+    stableList(route.permission),
+    stableList(route.dbTables),
+    stableList(route.dbColumns),
+    route.input.body,
+    route.input.form,
+    route.input.query,
+    route.input.params,
+  ]);
+}
+
+/** The pre-patch fact of the very same route, matched by file + method + path. */
+function prePatchRoute(state: EffectiveState, route: RouteFact): RouteFact | undefined {
+  const file = normalizeProjectPath(route.sourceFile);
+  return state.before.routes.find(
+    (candidate) =>
+      normalizeProjectPath(candidate.sourceFile) === file &&
+      candidate.method === route.method &&
+      candidate.path === route.path,
+  );
+}
+
+/** Rule 17: every patched route should carry one current English description. */
+export function routeDescriptionWarnings(state: EffectiveState): ValidationError[] {
+  const warnings: ValidationError[] = [];
+  for (const route of patchedRoutes(state)) {
+    // Rule 2 reports the wrapper error; a description for a broken route is not actionable.
+    if (route.wrapper !== "valid") continue;
+    const description = route.description;
+    if (description === null || description.trim() === "") {
+      warnings.push(
+        warning(
+          route,
+          "Route config must declare a description.",
+          "Add a one-sentence description of what the route does, in English, max " +
+            ROUTE_DESCRIPTION_MAX_CHARS +
+            " characters.",
+        ),
+      );
+      // Without text it cannot be over-long or stale (and the warning above already fires).
+      continue;
+    }
+    if (description.length > ROUTE_DESCRIPTION_MAX_CHARS) {
+      warnings.push(
+        warning(
+          route,
+          "The route description is " +
+            description.length +
+            " characters; keep it to " +
+            ROUTE_DESCRIPTION_MAX_CHARS +
+            " (about two lines).",
+          "Shorten the description to one English sentence of at most " +
+            ROUTE_DESCRIPTION_MAX_CHARS +
+            " characters.",
+        ),
+      );
+    }
+    const previous = prePatchRoute(state, route);
+    if (previous === undefined) continue;
+    if (previous.description !== description) continue;
+    if (contractSignature(previous) === contractSignature(route)) continue;
+    warnings.push(
+      warning(
+        route,
+        "The route's contract changed but its description did not, so the description may no longer be accurate.",
+        "Update the description to match the route's permission, input schemas, dbTables and dbColumns.",
+      ),
+    );
+  }
+  return warnings;
+}