@facilis.dev/ai 0.0.0-stage → 0.1.0

package/src/testing/fixtures.ts

@@ -0,0 +1,210 @@
+/**
+ * Shared fixtures for the validator tests: a realistic todo-app project analyzed with
+ * @facilis.dev/analyze, plus the patch overlay applied to its file map.
+ *
+ * Tests build the effective (post-patch) Analysis exactly as the IDE does — project the
+ * patch onto the pre-patch file map and analyze the result — so every rule runs against
+ * AST facts instead of a tolerant text scan.
+ */
+
+import {
+  buildProjectContext,
+  validatePatch,
+  type FilePatch,
+  type ImportAlias,
+  type PatchContext,
+  type SyntaxCheck,
+  type ValidatePatchOptions,
+  type ValidationResult,
+} from "../index.ts";
+import { normalizeProjectPath } from "../paths.ts";
+import { analyzeProjectSources } from "../node.ts";
+
+export const CONFIG = `import { defineConfig } from "@facilis.dev/core";
+
+export default defineConfig({
+  release: { ref: "origin/main" },
+  db: { mode: "pglite", migrationsDir: "db/migrations" },
+  i18n: { defaultLocale: "en", locales: ["en"] },
+  auth: {
+    permissions: ["todos:read", "todos:write"],
+    roles: { admin: ["*"], user: ["todos:read", "todos:write"] },
+    defaultRole: "user",
+  },
+});
+`;
+
+export const CONFIG_IT = CONFIG.replace(
+  'i18n: { defaultLocale: "en", locales: ["en"] },',
+  'i18n: { defaultLocale: "it", locales: ["en", "it"] },',
+);
+
+export const SCHEMA = `import { boolean, pgTable, text, uuid } from "drizzle-orm/pg-core";
+import { ownerIsolationPolicy, tenantColumn, tenantIsolationPolicy } from "@facilis.dev/db";
+
+export const todos = pgTable(
+  "todos",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    tenantId: tenantColumn(),
+    ownerId: uuid("owner_id").notNull(),
+    title: text("title").notNull(),
+    done: boolean("done").notNull().default(false),
+  },
+  () => [tenantIsolationPolicy(), ownerIsolationPolicy()],
+).enableRLS();
+`;
+
+const LOCALES =
+  JSON.stringify({ "app.title": "Facilis todos", "todos.title": "Todos" }, null, 2) + "\n";
+
+const PACKAGE_JSON =
+  JSON.stringify(
+    {
+      dependencies: {
+        "@facilis.dev/blocks": "workspace:*",
+        "@facilis.dev/core": "workspace:*",
+        "@facilis.dev/db": "workspace:*",
+        "drizzle-orm": "0.45.4",
+        react: "19.3.1",
+        zod: "4.6.7",
+      },
+      devDependencies: { typescript: "7.0.2", vite: "8.3.5" },
+    },
+    null,
+    2,
+  ) + "\n";
+
+const TSCONFIG = JSON.stringify({ compilerOptions: { paths: { "~/*": ["./*"] } } }, null, 2) + "\n";
+
+export const ROUTE_SOURCE = `import { z } from "zod";
+import { defineAuthorizedHandler } from "@facilis.dev/core";
+import { todos } from "~/db/schema";
+
+export default defineAuthorizedHandler(
+  {
+    permission: ["todos:read"],
+    query: z.object({ includeDone: z.enum(["true", "false"]).optional() }),
+    dbTables: ["todos"],
+    dbColumns: ["todos.title", "todos.done"],
+  },
+  async (_event, { query, db }) => db.select().from(todos),
+);
+`;
+
+/** Path aliases the Node analyzer gets, mirroring tsconfig's "~/*": ["./*"]. */
+const ANALYZER_ALIASES: readonly ImportAlias[] = [{ prefix: "~/", target: "" }];
+
+/** Registered blocks and a manifest-only catalog key (the fallback merge test reads it). */
+export function manifest(): unknown {
+  return {
+    blocks: [{ name: "DataTable" }, { name: "ResourceForm" }],
+    i18n: { defaultLocale: "en", catalogs: { en: { "manifest.only": "Manifest fallback" } } },
+  };
+}
+
+export const BASE_SOURCES: Readonly<Record<string, string>> = {
+  "facilis.config.ts": CONFIG,
+  "db/schema.ts": SCHEMA,
+  "locales/en.json": LOCALES,
+  "locales/it.json": LOCALES,
+  "package.json": PACKAGE_JSON,
+  "tsconfig.json": TSCONFIG,
+  "server/routes/api/todos/index.get.ts": ROUTE_SOURCE,
+  "src/lib/i18n.ts": "export const t = (key: string) => key;\n",
+  "src/lib/api.ts": "export const api = true;\n",
+};
+
+/** Project the patch set onto a file map, like the IDE's apply-to-VFS projection. */
+export function applyPatches(
+  base: ReadonlyMap<string, string>,
+  patches: readonly FilePatch[],
+): Map<string, string> {
+  const files = new Map(base);
+  for (const patch of patches) {
+    const path = normalizeProjectPath(patch.path);
+    if (patch.action === "delete") {
+      files.delete(path);
+      continue;
+    }
+    if (typeof patch.content === "string") files.set(path, patch.content);
+  }
+  return files;
+}
+
+export interface ContextOptions {
+  /** Base-source overrides (the pre-patch project). */
+  sources?: Readonly<Record<string, string>>;
+  /** Base files to drop (e.g. locales/en.json, to exercise the locale fallback). */
+  omit?: readonly string[];
+  /** Pre-patch file list; defaults to the base source keys. */
+  files?: readonly string[];
+  manifest?: unknown;
+  syntax?: SyntaxCheck;
+  packages?: readonly string[];
+  aliases?: readonly ImportAlias[];
+}
+
+/** Build the effective PatchContext for one patch set. */
+export function makeContext(
+  patches: readonly FilePatch[] = [],
+  options: ContextOptions = {},
+): PatchContext {
+  const base: Record<string, string> = { ...BASE_SOURCES, ...options.sources };
+  for (const path of options.omit ?? []) delete base[path];
+  const baseMap = new Map(Object.entries(base));
+  const effectiveMap = applyPatches(baseMap, patches);
+  const before = analyzeProjectSources(baseMap, ANALYZER_ALIASES);
+  const analysis = analyzeProjectSources(effectiveMap, ANALYZER_ALIASES);
+  const sources: Record<string, string> = {};
+  for (const path of ["package.json", "tsconfig.json"]) {
+    const content = effectiveMap.get(path);
+    if (content !== undefined) sources[path] = content;
+  }
+  const project = buildProjectContext({
+    files: options.files ?? [...baseMap.keys()],
+    analysis,
+    before,
+    manifest: options.manifest === undefined ? manifest() : options.manifest,
+    sources,
+    ...(options.packages === undefined ? {} : { packages: options.packages }),
+    ...(options.aliases === undefined ? {} : { aliases: options.aliases }),
+  });
+  return { ...project, syntax: options.syntax ?? { status: "checked", findings: [] } };
+}
+
+export interface ValidateOptions extends ContextOptions {
+  requiresConfirmation?: boolean;
+  allowedRootFiles?: readonly string[];
+}
+
+/** Build the context for the patch set, then validate it (the IDE's whole round). */
+export function validate(
+  patches: readonly FilePatch[],
+  options: ValidateOptions = {},
+): { result: ValidationResult; context: PatchContext } {
+  const context = makeContext(patches, options);
+  const overrides: Pick<ValidatePatchOptions, "requiresConfirmation" | "allowedRootFiles"> = {};
+  if (options.requiresConfirmation !== undefined) {
+    overrides.requiresConfirmation = options.requiresConfirmation;
+  }
+  if (options.allowedRootFiles !== undefined) overrides.allowedRootFiles = options.allowedRootFiles;
+  const result = validatePatch(patches, { context, ...overrides });
+  return { result, context };
+}
+
+export function create(path: string, content: string): FilePatch {
+  return { path, action: "create", content };
+}
+
+export function update(path: string, content: string): FilePatch {
+  return { path, action: "update", content };
+}
+
+export function remove(path: string): FilePatch {
+  return { path, action: "delete" };
+}
+
+export function rulesOf(entries: readonly { rule: string }[]): string[] {
+  return entries.map((entry) => entry.rule);
+}

package/src/types.ts

@@ -0,0 +1,164 @@
+/**
+ * Shared contracts of the SPEC §9.3 patch validator.
+ *
+ * Project facts now come from @facilis.dev/analyze's AST interpreter (D-092), not from local
+ * text scanners. This module only imports analyzer *types* (erased at build), so the main
+ * entry keeps its browser-safety guarantee: no analyzer runtime value is loaded.
+ *
+ * The caller supplies the effective post-patch {@link Analysis} plus, optionally, the
+ * pre-patch one. `null` means unknown and `[]` means explicitly empty, exactly as in the
+ * analyzer's fact model.
+ */
+
+import type {
+  Analysis,
+  ConfigFacts as AnalyzerConfigFacts,
+  RouteFact as AnalyzerRouteFact,
+  TableFact as AnalyzerTableFact,
+} from "@facilis.dev/analyze";
+
+export type { Analysis, AnalyzerConfigFacts, AnalyzerRouteFact, AnalyzerTableFact };
+export type {
+  ColumnFact,
+  Diagnostic,
+  FileFacts,
+  ImportFact,
+  JobFact,
+  JobRelationsFact,
+  LocaleCatalogs,
+  RouteElevationUsage,
+  RouteRelationUse,
+  RouteRelationsFact,
+  SourceRef,
+  TranslationCallFact,
+  ViewFact,
+} from "@facilis.dev/analyze";
+
+/** Readable aliases for the analyzer facts the rules consume. */
+export type ConfigFacts = AnalyzerConfigFacts;
+export type RouteFact = AnalyzerRouteFact;
+export type TableFact = AnalyzerTableFact;
+
+/** One proposed file write (SPEC §9.2 response contract). */
+export interface FilePatch {
+  path: string;
+  action: "create" | "update" | "delete";
+  content?: string;
+}
+
+/** One validator finding (SPEC §7.6): machine-readable rule id plus file and detail. */
+export interface ValidationError {
+  rule: string;
+  severity: "error" | "warning";
+  file: string;
+  /** The detail a caller can show or feed back to the model; never prose-free UI copy. */
+  message: string;
+  /** What to change to clear the finding. */
+  fix_hint: string;
+  /**
+   * The finding is about the validator's own plumbing (parser/analyzer unavailable), not the
+   * patch. The IDE must not ask the model to repair it; it retries or reports it to the user.
+   */
+  infrastructure?: boolean;
+  line?: number;
+  column?: number;
+  /** The offending source line, capped, when it is cheap to provide. */
+  excerpt?: string;
+}
+
+export interface ValidationResult {
+  ok: boolean;
+  errors: ValidationError[];
+  warnings: ValidationError[];
+}
+
+/** One parse diagnostic from the injected TypeScript service (rule 1). */
+export interface SyntaxIssue {
+  line: number;
+  column: number;
+  message: string;
+}
+
+export interface SyntaxFinding extends SyntaxIssue {
+  file: string;
+}
+
+/**
+ * The rule-1 seam. The IDE injects the analyzer worker's oxc parser; Node tooling injects
+ * `@facilis.dev/ai/node` (the subpath is the only place that imports a parser).
+ */
+export interface SyntaxChecker {
+  check(path: string, content: string): Promise<readonly SyntaxIssue[]>;
+}
+
+/** Rule 1's input: "unavailable" makes the rule fail closed for script patches. */
+export type SyntaxCheck =
+  | { status: "checked"; findings: readonly SyntaxFinding[] }
+  | { status: "unavailable"; reason: string };
+
+/** One registered block component (live manifest only; not a source fact; reserved, D-131). */
+export interface BlockFacts {
+  name: string;
+}
+
+/** A tsconfig `paths` alias such as `"~/": ""` (project-relative target). */
+export interface ImportAlias {
+  prefix: string;
+  target: string;
+}
+
+/** Raw material a caller assembles before the validator runs. */
+export interface ProjectContextInput {
+  /** Project-relative paths that exist before the patch (the pre-patch file set). */
+  files: readonly string[];
+  /** The effective (post-patch) analysis: the facts the rules must validate. */
+  analysis: Analysis;
+  /** The pre-patch analysis, for inverse edits. Defaults to `analysis`. */
+  before?: Analysis;
+  /** The `/__facilis/manifest` envelope's manifest: blocks and catalog fallback only. */
+  manifest?: unknown;
+  /** Installed bare specifiers; derived from package.json when omitted. */
+  packages?: readonly string[];
+  aliases?: readonly ImportAlias[];
+  /** Only `package.json` and `tsconfig.json` are read from here; everything else is facts. */
+  sources?: Readonly<Record<string, string>>;
+}
+
+export interface SchemaSummary {
+  readonly parsed: boolean;
+  readonly tables: readonly TableFact[];
+}
+
+/** The typed project context every context-dependent rule reads. */
+export interface ProjectContext {
+  files: readonly string[];
+  /** Effective (post-patch) facts. */
+  analysis: Analysis;
+  /** Pre-patch facts; equal to `analysis` when the caller has none. */
+  before: Analysis;
+  config: ConfigFacts;
+  schema: SchemaSummary;
+  /** Flattened default-locale catalogue (analyzer first, manifest fallback). */
+  locales: Readonly<Record<string, string>>;
+  blocks: readonly BlockFacts[];
+  routes: readonly RouteFact[];
+  packages: readonly string[];
+  aliases: readonly ImportAlias[];
+}
+
+/** The complete validator input: the project context plus the rule-1 result. */
+export interface PatchContext extends ProjectContext {
+  syntax: SyntaxCheck;
+}
+
+export interface ValidatePatchOptions {
+  /** Without a context only the context-free structural rules run (parser gate). */
+  context?: PatchContext;
+  /** The AIResponse `requires_confirmation` flag, for rule 15. */
+  requiresConfirmation?: boolean;
+  /**
+   * Extra root files this write may touch. Only the IDE's own writers pass it (e.g. the
+   * AGENTS.md scaffold); AI patches never do, so the model cannot persist instructions.
+   */
+  allowedRootFiles?: readonly string[];
+}

package/src/validator.ts

@@ -0,0 +1,71 @@
+/**
+ * The SPEC §9.3 patch validator: 19 rules, grouped by the part of the project they read.
+ *
+ * Without a context only the two context-free structural checks run (the parser gate);
+ * with a context the full rule set runs. Rules 5, 13, 14 and 17 are warnings (they never
+ * block); the others are errors and make `ok` false, which is what stops the IDE's apply
+ * path before it writes anything (invariant 9).
+ *
+ * Every contextual rule reads @facilis.dev/analyze's fact model (D-092): the effective
+ * post-patch Analysis supplied by the caller, never a re-parse of the patch text.
+ */
+
+import { buildEffectiveState } from "./overlay.ts";
+import { blockImportErrors } from "./rules/blocks.ts";
+import { roleConfigSyncErrors } from "./rules/config-sync.ts";
+import { destructiveErrors, migrationWarnings, rlsErrors } from "./rules/database.ts";
+import { i18nWarnings } from "./rules/i18n.ts";
+import { importResolveErrors, rawDbAccessErrors } from "./rules/imports.ts";
+import { jobTableDeclaredFindings } from "./rules/job-relations.ts";
+import { routeTableDeclaredFindings } from "./rules/route-relations.ts";
+import { routeDescriptionWarnings } from "./rules/routes-description.ts";
+import {
+  permissionErrors,
+  routeDbColumnsWarnings,
+  routeDbTablesErrors,
+} from "./rules/routes-metadata.ts";
+import {
+  routeDbTablesPresentErrors,
+  routeInputErrors,
+  routeSecurityErrors,
+} from "./rules/routes-security.ts";
+import { structuralErrors } from "./rules/structural.ts";
+import { tsParseErrors } from "./rules/ts-parse.ts";
+import type { FilePatch, ValidatePatchOptions, ValidationResult } from "./types.ts";
+
+export function validatePatch(
+  patches: readonly FilePatch[],
+  options: ValidatePatchOptions = {},
+): ValidationResult {
+  const errors = structuralErrors(patches, options.allowedRootFiles);
+  const warnings: ValidationResult["warnings"] = [];
+  const context = options.context;
+  if (context !== undefined) {
+    const state = buildEffectiveState(context, patches);
+    errors.push(...tsParseErrors(patches, context.syntax));
+    errors.push(...routeSecurityErrors(state));
+    errors.push(...routeDbTablesPresentErrors(state));
+    errors.push(...routeDbTablesErrors(state));
+    warnings.push(...routeDbColumnsWarnings(state));
+    errors.push(...permissionErrors(state));
+    errors.push(...blockImportErrors(state, context));
+    errors.push(...routeInputErrors(state));
+    errors.push(...rawDbAccessErrors(state));
+    errors.push(...rlsErrors(state));
+    errors.push(...importResolveErrors(state, context));
+    warnings.push(...i18nWarnings(state));
+    warnings.push(...migrationWarnings(patches, state));
+    errors.push(...destructiveErrors(state, options.requiresConfirmation === true));
+    errors.push(...roleConfigSyncErrors(patches, state));
+    warnings.push(...routeDescriptionWarnings(state));
+    // D-157 rule 18: dbTables is applied over every effective route, not only patched ones.
+    const routeTables = routeTableDeclaredFindings(state);
+    errors.push(...routeTables.errors);
+    warnings.push(...routeTables.warnings);
+    // D-157 rule 19: the same declaration, applied to every effective job's system client.
+    const jobTables = jobTableDeclaredFindings(state);
+    errors.push(...jobTables.errors);
+    warnings.push(...jobTables.warnings);
+  }
+  return { ok: errors.length === 0, errors, warnings };
+}