@facilis.dev/ai 0.0.0-stage → 0.1.0

package/src/rules/routes-metadata.ts

@@ -0,0 +1,241 @@
+/**
+ * Rules 4 `db-tables-valid`, 5 `db-columns-valid` and 6 `permission-valid` (SPEC §9.3).
+ *
+ * The rules read the route facts the analyzer produced and check them against the effective
+ * facts: the schema tables (Drizzle property names for columns) and the config's permission
+ * list. They also catch the inverse edit: removing a table, column or permission that an
+ * existing route still references.
+ */
+
+import type { EffectiveState } from "../overlay.ts";
+import { normalizeProjectPath } from "../paths.ts";
+import type { RouteFact, TableFact, ValidationError } from "../types.ts";
+import { patchedRoutes } from "./routes-security.ts";
+
+const COLUMN_REFERENCE = /^[A-Za-z_$][\w$]*\.[A-Za-z_$][\w$]*$/;
+
+function tableLookup(tables: readonly TableFact[]): Map<string, TableFact> {
+  const lookup = new Map<string, TableFact>();
+  for (const table of tables) {
+    lookup.set(table.name, table);
+    if (table.binding !== null) lookup.set(table.binding, table);
+  }
+  return lookup;
+}
+
+function untouchedByPatch(route: RouteFact, state: EffectiveState): boolean {
+  const file = normalizeProjectPath(route.sourceFile);
+  return !state.patchedPaths.has(file) && !state.deletedPaths.has(file);
+}
+
+function routeLabel(route: RouteFact): string {
+  return route.method + " " + route.path;
+}
+
+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 }),
+  };
+}
+
+function warning(
+  rule: string,
+  file: string,
+  message: string,
+  fix_hint: string,
+  line?: number,
+): ValidationError {
+  return {
+    rule,
+    severity: "warning",
+    file,
+    message,
+    fix_hint,
+    ...(line === undefined ? {} : { line }),
+  };
+}
+
+/** Rule 4: every declared `dbTables` entry must be a table or view the project declares. */
+export function routeDbTablesErrors(state: EffectiveState): ValidationError[] {
+  // D-157: a view is declared by its own SQL name (the base tables stay in the view).
+  const known = new Set(tableLookup(state.schemaTables).keys());
+  for (const view of state.analysis.views ?? []) {
+    known.add(view.name);
+    if (view.binding !== null) known.add(view.binding);
+  }
+  const errors: ValidationError[] = [];
+  for (const route of patchedRoutes(state)) {
+    for (const table of route.dbTables ?? []) {
+      if (known.has(table)) continue;
+      errors.push(
+        error(
+          "db-tables-valid",
+          route.sourceFile,
+          'dbTables references relation "' + table + '", which is not in the schema.',
+          "Use a table or view declared in db/ (or added by this patch), or drop the reference.",
+          route.source.line,
+        ),
+      );
+    }
+  }
+  for (const route of state.before.routes) {
+    if (!untouchedByPatch(route, state)) continue;
+    for (const table of route.dbTables ?? []) {
+      if (!state.removedTables.includes(table)) continue;
+      errors.push(
+        error(
+          "db-tables-valid",
+          route.sourceFile,
+          'The patch removes table "' +
+            table +
+            '", which the existing route ' +
+            routeLabel(route) +
+            " still references.",
+          "Update the route (or delete it) in the same patch, or keep the table. If the change was meant to be additive, re-emit db/schema.ts with every existing table plus the new one.",
+        ),
+      );
+    }
+  }
+  return errors;
+}
+
+/** Columns (Drizzle property names) dropped by the patch, keyed table.property. */
+function removedColumns(state: EffectiveState): { table: string; column: string }[] {
+  const before = new Map(state.beforeSchemaTables.map((table) => [table.name, table]));
+  const removed: { table: string; column: string }[] = [];
+  for (const table of state.afterSchemaTables) {
+    const previous = before.get(table.name);
+    if (previous === undefined || previous.columns.length === 0 || table.columns.length === 0) {
+      continue;
+    }
+    const current = new Set(table.columns.map((column) => column.property));
+    for (const column of previous.columns) {
+      if (!current.has(column.property))
+        removed.push({ table: table.name, column: column.property });
+    }
+  }
+  return removed;
+}
+
+/** Rule 5: `dbColumns` entries are `table.property` references into the effective schema. */
+export function routeDbColumnsWarnings(state: EffectiveState): ValidationError[] {
+  const lookup = tableLookup(state.schemaTables);
+  const warnings: ValidationError[] = [];
+  const warn = (file: string, message: string, fix_hint: string, line?: number): void => {
+    warnings.push(warning("db-columns-valid", file, message, fix_hint, line));
+  };
+  for (const route of patchedRoutes(state)) {
+    for (const reference of route.dbColumns ?? []) {
+      if (!COLUMN_REFERENCE.test(reference)) {
+        warn(
+          route.sourceFile,
+          '"' + reference + '" is not a "table.column" reference.',
+          "Declare dbColumns entries as table.column using Drizzle property names.",
+          route.source.line,
+        );
+        continue;
+      }
+      const [tableName, columnName] = reference.split(".");
+      if (tableName === undefined || columnName === undefined) continue;
+      const table = lookup.get(tableName);
+      if (table === undefined) {
+        warn(
+          route.sourceFile,
+          'dbColumns references table "' + tableName + '", which is not in the schema.',
+          "Use a table declared in db/schema.ts.",
+          route.source.line,
+        );
+      } else if (
+        table.columns.length > 0 &&
+        !table.columns.some((column) => column.property === columnName)
+      ) {
+        warn(
+          route.sourceFile,
+          'dbColumns references unknown column "' + columnName + '" on table "' + tableName + '".',
+          "Use a column the schema declares, or update dbColumns with the patch.",
+          route.source.line,
+        );
+      }
+    }
+  }
+  const dropped = removedColumns(state);
+  for (const route of state.before.routes) {
+    if (!untouchedByPatch(route, state)) continue;
+    for (const reference of route.dbColumns ?? []) {
+      const removed = dropped.some((entry) => entry.table + "." + entry.column === reference);
+      if (!removed) continue;
+      warn(
+        route.sourceFile,
+        'The patch drops "' +
+          reference +
+          '", which the existing route ' +
+          routeLabel(route) +
+          " still references.",
+        "Update the route in the same patch, or keep the column.",
+      );
+    }
+  }
+  return warnings;
+}
+
+/** Rule 6: every route permission must be declared in `facilis.config.ts`; null fails closed. */
+export function permissionErrors(state: EffectiveState): ValidationError[] {
+  const declared = new Set(state.config.permissions);
+  const errors: ValidationError[] = [];
+  for (const route of patchedRoutes(state)) {
+    if (route.permission === null) {
+      errors.push(
+        error(
+          "permission-valid",
+          route.sourceFile,
+          "Route config must declare permission ([] for a public route).",
+          'Add permission: ["..."] or permission: [] to defineAuthorizedHandler (SPEC §7.4).',
+          route.source.line,
+        ),
+      );
+      continue;
+    }
+    for (const value of route.permission) {
+      if (declared.has(value)) continue;
+      errors.push(
+        error(
+          "permission-valid",
+          route.sourceFile,
+          'Permission "' + value + '" is not declared in facilis.config.ts.',
+          "Declare it in auth.permissions (and roles) in the same patch, or use an existing permission.",
+          route.source.line,
+        ),
+      );
+    }
+  }
+  for (const route of state.before.routes) {
+    if (!untouchedByPatch(route, state)) continue;
+    for (const permission of route.permission ?? []) {
+      if (!state.removedPermissions.includes(permission)) continue;
+      errors.push(
+        error(
+          "permission-valid",
+          route.sourceFile,
+          'The patch removes permission "' +
+            permission +
+            '", which the existing route ' +
+            routeLabel(route) +
+            " still requires.",
+          "Update the route in the same patch, or keep the permission declared.",
+        ),
+      );
+    }
+  }
+  return errors;
+}

package/src/rules/routes-security.ts

@@ -0,0 +1,90 @@
+/**
+ * Rules 2 `route-security`, 3 `db-tables-present` and 8 `route-input-validated`
+ * (SPEC §9.3), checked on the routes whose source file the patch creates or updates.
+ *
+ * The facts come from @facilis.dev/analyze's route pass: wrapper resolution, `dbTables` and the
+ * handler's body read are AST facts, so a route cannot look valid by mentioning the wrapper
+ * in a comment or a string. A route file with an invalid wrapper is still listed by the
+ * analyzer, which is what lets rule 2 see it.
+ */
+
+import type { EffectiveState } from "../overlay.ts";
+import { normalizeProjectPath } from "../paths.ts";
+import type { RouteFact, ValidationError } from "../types.ts";
+
+/** Routes whose source file the patch creates or updates (deleted files have no facts). */
+export function patchedRoutes(state: EffectiveState): RouteFact[] {
+  return state.analysis.routes.filter((route) =>
+    state.patchedPaths.has(normalizeProjectPath(route.sourceFile)),
+  );
+}
+
+function error(rule: string, route: RouteFact, message: string, fix_hint: string): ValidationError {
+  return {
+    rule,
+    severity: "error",
+    file: route.sourceFile,
+    message,
+    fix_hint,
+    line: route.source.line,
+  };
+}
+
+/** Rule 2: the default export must be the resolved `defineAuthorizedHandler` call. */
+export function routeSecurityErrors(state: EffectiveState): ValidationError[] {
+  return patchedRoutes(state)
+    .filter((route) => route.wrapper !== "valid")
+    .map((route) =>
+      error(
+        "route-security",
+        route,
+        "Every API route must be written with defineAuthorizedHandler.",
+        "Wrap the handler in defineAuthorizedHandler (security invariant 1).",
+      ),
+    );
+}
+
+/** Rule 3: `dbTables` must be present; unknown (null) fails closed. */
+export function routeDbTablesPresentErrors(state: EffectiveState): ValidationError[] {
+  return patchedRoutes(state)
+    .filter((route) => route.dbTables === null)
+    .map((route) =>
+      error(
+        "db-tables-present",
+        route,
+        "Route config must declare dbTables (an empty array when it touches no table).",
+        "Add dbTables: [] or the list of tables the handler uses (security invariant 2).",
+      ),
+    );
+}
+
+/**
+ * Rule 8: a handler that reads the request input must declare the matching schema — `body`
+ * for a JSON body, `form` for a multipart/form-data body (D-053).
+ */
+export function routeInputErrors(state: EffectiveState): ValidationError[] {
+  return patchedRoutes(state).flatMap((route) => {
+    const errors: ValidationError[] = [];
+    if (route.handlerBodyRead && !route.input.body) {
+      errors.push(
+        error(
+          "route-input-validated",
+          route,
+          "The handler reads the request body but the route declares no body schema.",
+          "Declare body: <ZodSchema> in the defineAuthorizedHandler config for a JSON body (security invariant 3).",
+        ),
+      );
+    }
+    if (route.handlerFormRead && !route.input.form) {
+      errors.push(
+        error(
+          "route-input-validated",
+          route,
+          "The handler reads the multipart form but the route declares no form schema.",
+          "Declare form: <ZodSchema> in the defineAuthorizedHandler config for a multipart/form-data upload (security invariant 3).",
+        ),
+      );
+    }
+    return errors;
+  });
+}

package/src/rules/structural.ts

@@ -0,0 +1,63 @@
+/**
+ * Rule 11 `file-path-allowed` plus the two structural checks the parser owns
+ * (relative path, content present). These need no project context, so they also run
+ * when the parser validates a raw answer before any context is assembled.
+ */
+
+import { isAllowedWritePath, normalizeProjectPath } from "../paths.ts";
+import type { FilePatch, ValidationError } from "../types.ts";
+
+const UNSAFE_SEGMENTS = new Set(["..", "."]);
+
+function error(rule: string, file: string, message: string, fix_hint: string): ValidationError {
+  return { rule, severity: "error", file, message, fix_hint };
+}
+
+export function structuralErrors(
+  patches: readonly FilePatch[],
+  allowedRootFiles: readonly string[] = [],
+): ValidationError[] {
+  const errors: ValidationError[] = [];
+  for (const patch of patches) {
+    const path = normalizeProjectPath(patch.path);
+    const segments = path.split("/");
+    const unsafe =
+      patch.path.trim().length === 0 ||
+      patch.path.startsWith("/") ||
+      segments.some((segment) => UNSAFE_SEGMENTS.has(segment));
+    if (unsafe) {
+      errors.push(
+        error(
+          "file-path-allowed",
+          patch.path,
+          "Patch paths must be relative to the project root.",
+          "Use a project-relative path with no leading slash and no '..' segment.",
+        ),
+      );
+      continue;
+    }
+    if (!isAllowedWritePath(path) && !allowedRootFiles.includes(path)) {
+      errors.push(
+        error(
+          "file-path-allowed",
+          patch.path,
+          '"' +
+            path +
+            '" is outside the writable roots (server/, src/, db/, lib/, components/, locales/, facilis.config.ts).',
+          "Keep the patch under server/, src/, db/, lib/, components/ or locales/; the only allowed root file is facilis.config.ts.",
+        ),
+      );
+    }
+    if (patch.action !== "delete" && (patch.content ?? "").length === 0) {
+      errors.push(
+        error(
+          "content-present",
+          patch.path,
+          "Create and update patches must include file content.",
+          "Emit the complete new file content for every create and update patch.",
+        ),
+      );
+    }
+  }
+  return errors;
+}

package/src/rules/ts-parse.ts

@@ -0,0 +1,71 @@
+/**
+ * Rule 1 `ts-parse` (SPEC §9.3): every script file the patch writes must parse.
+ *
+ * The parser itself is injected — the IDE passes the analyzer worker's oxc parser, Node
+ * tooling passes `@facilis.dev/ai/node` — so `@facilis.dev/ai` never imports TypeScript. When the
+ * injected checker is unavailable the rule fails closed: a patch is never written with
+ * rule 1 silently skipped.
+ */
+
+import { isScriptPath, normalizeProjectPath } from "../paths.ts";
+import type { FilePatch, SyntaxCheck, ValidationError } from "../types.ts";
+
+export interface ScriptSource {
+  path: string;
+  content: string;
+}
+
+/** Create/update patches that carry a script file, in patch order. */
+export function scriptSources(patches: readonly FilePatch[]): ScriptSource[] {
+  const sources: ScriptSource[] = [];
+  for (const patch of patches) {
+    if (patch.action === "delete" || patch.content === undefined) continue;
+    const path = normalizeProjectPath(patch.path);
+    if (isScriptPath(path)) sources.push({ path, content: patch.content });
+  }
+  return sources;
+}
+
+function excerptOf(content: string, line: number): string | undefined {
+  const text = content.split("\n")[line - 1];
+  if (text === undefined) return undefined;
+  const trimmed = text.trim();
+  return trimmed.length > 160 ? trimmed.slice(0, 160) + "…" : trimmed;
+}
+
+export function tsParseErrors(
+  patches: readonly FilePatch[],
+  syntax: SyntaxCheck,
+): ValidationError[] {
+  const sources = scriptSources(patches);
+  if (sources.length === 0) return [];
+  if (syntax.status === "unavailable") {
+    return sources.map((source) => ({
+      rule: "ts-parse",
+      severity: "error",
+      file: source.path,
+      message: "TypeScript syntax could not be checked: " + syntax.reason,
+      fix_hint:
+        "Wait for the editor's TypeScript service to load and retry; rule 1 fails closed on purpose.",
+      infrastructure: true,
+    }));
+  }
+  const byFile = new Map(sources.map((source) => [source.path, source]));
+  const errors: ValidationError[] = [];
+  for (const finding of syntax.findings) {
+    const source = byFile.get(finding.file);
+    if (source === undefined) continue;
+    const excerpt = excerptOf(source.content, finding.line);
+    errors.push({
+      rule: "ts-parse",
+      severity: "error",
+      file: finding.file,
+      message: finding.message,
+      fix_hint: "Fix the TypeScript syntax error; a file that does not parse cannot be applied.",
+      line: finding.line,
+      column: finding.column,
+      ...(excerpt === undefined ? {} : { excerpt }),
+    });
+  }
+  return errors;
+}

package/src/syntax-runner.ts

@@ -0,0 +1,33 @@
+/**
+ * Runs the injected TypeScript parser over the patch's script files (rule 1).
+ *
+ * Kept separate from the rule so the async parser call happens once, before the pure
+ * validator runs: `checkPatchSyntax()` is the only async step of validation.
+ */
+
+import { scriptSources } from "./rules/ts-parse.ts";
+import type { FilePatch, SyntaxChecker, SyntaxFinding } from "./types.ts";
+
+export async function checkPatchSyntax(
+  patches: readonly FilePatch[],
+  checker: SyntaxChecker,
+): Promise<SyntaxFinding[]> {
+  const checked = await Promise.all(
+    scriptSources(patches).map(async (source) => ({
+      source,
+      issues: await checker.check(source.path, source.content),
+    })),
+  );
+  const findings: SyntaxFinding[] = [];
+  for (const entry of checked) {
+    for (const issue of entry.issues) {
+      findings.push({
+        file: entry.source.path,
+        line: issue.line,
+        column: issue.column,
+        message: issue.message,
+      });
+    }
+  }
+  return findings;
+}