@facilis.dev/ai 0.0.0-stage → 0.1.1

package/dist/testing/fixtures.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 { type FilePatch, type ImportAlias, type PatchContext, type SyntaxCheck, type ValidatePatchOptions, type ValidationResult } from "../index.js";
+export declare const CONFIG = "import { defineConfig } from \"@facilis.dev/core\";\n\nexport default defineConfig({\n  release: { ref: \"origin/main\" },\n  db: { mode: \"pglite\", migrationsDir: \"db/migrations\" },\n  i18n: { defaultLocale: \"en\", locales: [\"en\"] },\n  auth: {\n    permissions: [\"todos:read\", \"todos:write\"],\n    roles: { admin: [\"*\"], user: [\"todos:read\", \"todos:write\"] },\n    defaultRole: \"user\",\n  },\n});\n";
+export declare const CONFIG_IT: string;
+export declare const SCHEMA = "import { boolean, pgTable, text, uuid } from \"drizzle-orm/pg-core\";\nimport { ownerIsolationPolicy, tenantColumn, tenantIsolationPolicy } from \"@facilis.dev/db\";\n\nexport const todos = pgTable(\n  \"todos\",\n  {\n    id: uuid(\"id\").primaryKey().defaultRandom(),\n    tenantId: tenantColumn(),\n    ownerId: uuid(\"owner_id\").notNull(),\n    title: text(\"title\").notNull(),\n    done: boolean(\"done\").notNull().default(false),\n  },\n  () => [tenantIsolationPolicy(), ownerIsolationPolicy()],\n).enableRLS();\n";
+export declare const ROUTE_SOURCE = "import { z } from \"zod\";\nimport { defineAuthorizedHandler } from \"@facilis.dev/core\";\nimport { todos } from \"~/db/schema\";\n\nexport default defineAuthorizedHandler(\n  {\n    permission: [\"todos:read\"],\n    query: z.object({ includeDone: z.enum([\"true\", \"false\"]).optional() }),\n    dbTables: [\"todos\"],\n    dbColumns: [\"todos.title\", \"todos.done\"],\n  },\n  async (_event, { query, db }) => db.select().from(todos),\n);\n";
+/** Registered blocks and a manifest-only catalog key (the fallback merge test reads it). */
+export declare function manifest(): unknown;
+export declare const BASE_SOURCES: Readonly<Record<string, string>>;
+/** Project the patch set onto a file map, like the IDE's apply-to-VFS projection. */
+export declare function applyPatches(base: ReadonlyMap<string, string>, patches: readonly FilePatch[]): Map<string, string>;
+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 declare function makeContext(patches?: readonly FilePatch[], options?: ContextOptions): PatchContext;
+export interface ValidateOptions extends ContextOptions {
+    requiresConfirmation?: boolean;
+    allowedRootFiles?: readonly string[];
+    writePolicy?: ValidatePatchOptions["writePolicy"];
+}
+/** Build the context for the patch set, then validate it (the IDE's whole round). */
+export declare function validate(patches: readonly FilePatch[], options?: ValidateOptions): {
+    result: ValidationResult;
+    context: PatchContext;
+};
+export declare function create(path: string, content: string): FilePatch;
+export declare function update(path: string, content: string): FilePatch;
+export declare function remove(path: string): FilePatch;
+export declare function rulesOf(entries: readonly {
+    rule: string;
+}[]): string[];

package/dist/testing/fixtures.js

@@ -0,0 +1,153 @@
+/**
+ * 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, } from "../index.js";
+import { normalizeProjectPath } from "../paths.js";
+import { analyzeProjectSources } from "../node.js";
+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 = [{ prefix: "~/", target: "" }];
+/** Registered blocks and a manifest-only catalog key (the fallback merge test reads it). */
+export function manifest() {
+    return {
+        blocks: [{ name: "DataTable" }, { name: "ResourceForm" }],
+        i18n: { defaultLocale: "en", catalogs: { en: { "manifest.only": "Manifest fallback" } } },
+    };
+}
+export const BASE_SOURCES = {
+    "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, patches) {
+    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;
+}
+/** Build the effective PatchContext for one patch set. */
+export function makeContext(patches = [], options = {}) {
+    const base = { ...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 = {};
+    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: [] } };
+}
+/** Build the context for the patch set, then validate it (the IDE's whole round). */
+export function validate(patches, options = {}) {
+    const context = makeContext(patches, options);
+    const overrides = {};
+    if (options.requiresConfirmation !== undefined) {
+        overrides.requiresConfirmation = options.requiresConfirmation;
+    }
+    if (options.allowedRootFiles !== undefined)
+        overrides.allowedRootFiles = options.allowedRootFiles;
+    if (options.writePolicy !== undefined)
+        overrides.writePolicy = options.writePolicy;
+    const result = validatePatch(patches, { context, ...overrides });
+    return { result, context };
+}
+export function create(path, content) {
+    return { path, action: "create", content };
+}
+export function update(path, content) {
+    return { path, action: "update", content };
+}
+export function remove(path) {
+    return { path, action: "delete" };
+}
+export function rulesOf(entries) {
+    return entries.map((entry) => entry.rule);
+}

package/dist/types.d.ts

@@ -0,0 +1,146 @@
+/**
+ * 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;
+/**
+ * Rule 11's writable set, selected by the deployment profile (D-167). `managed` keeps the
+ * six source roots (D-084); `open` accepts the whole project minus the install, VCS/IDE and
+ * instruction surfaces. The default is `managed`, so an external caller changes nothing.
+ */
+export type WritePolicy = "open" | "managed";
+/** 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[];
+    /**
+     * The patch set drops a table or a column (rule 15's predicate). The IDE's incremental
+     * write path records it on the turn journal; confirmation stays rule 15's business, so
+     * this can be true on a result that is also `ok`.
+     */
+    destructive?: boolean;
+}
+/** 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[];
+    /** Rule 11's writable set (D-167). Defaults to `managed`, the strict roots. */
+    writePolicy?: WritePolicy;
+}

package/dist/types.js

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+export {};

package/dist/validator.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 type { FilePatch, ValidatePatchOptions, ValidationResult } from "./types.js";
+export declare function validatePatch(patches: readonly FilePatch[], options?: ValidatePatchOptions): ValidationResult;

package/dist/validator.js

@@ -0,0 +1,62 @@
+/**
+ * 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.js";
+import { blockImportErrors } from "./rules/blocks.js";
+import { roleConfigSyncErrors } from "./rules/config-sync.js";
+import { destructiveChanges, destructiveErrors, migrationWarnings, rlsErrors, } from "./rules/database.js";
+import { i18nWarnings } from "./rules/i18n.js";
+import { importResolveErrors, rawDbAccessErrors } from "./rules/imports.js";
+import { jobTableDeclaredFindings } from "./rules/job-relations.js";
+import { routeTableDeclaredFindings } from "./rules/route-relations.js";
+import { routeDescriptionWarnings } from "./rules/routes-description.js";
+import { permissionErrors, routeDbColumnsWarnings, routeDbTablesErrors, } from "./rules/routes-metadata.js";
+import { routeDbTablesPresentErrors, routeInputErrors, routeSecurityErrors, } from "./rules/routes-security.js";
+import { structuralErrors } from "./rules/structural.js";
+import { tsParseErrors } from "./rules/ts-parse.js";
+export function validatePatch(patches, options = {}) {
+    const errors = structuralErrors(patches, {
+        allowedRootFiles: options.allowedRootFiles ?? [],
+        writePolicy: options.writePolicy ?? "managed",
+    });
+    const warnings = [];
+    let destructive = false;
+    const context = options.context;
+    if (context !== undefined) {
+        const state = buildEffectiveState(context, patches);
+        destructive = destructiveChanges(state).length > 0;
+        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, destructive };
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@facilis.dev/ai",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Facilis AI orchestration: prompt assembly, response parsing and patch validation.",
+  "license": "MIT",
+  "exports": {
+    ".": "./dist/index.js",
+    "./node": "./dist/node.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.15.0"
+  },
+  "dependencies": {
+    "@facilis.dev/analyze": "0.1.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/facilis-dev/facilis.git",
+    "directory": "packages/ai"
+  },
+  "homepage": "https://github.com/facilis-dev/facilis/tree/main/packages/ai#readme",
+  "bugs": {
+    "url": "https://github.com/facilis-dev/facilis/issues"
+  },
+  "keywords": [
+    "facilis",
+    "framework",
+    "vite",
+    "nitro",
+    "low-code"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}

package/src/context.ts

@@ -0,0 +1,117 @@
+/**
+ * Assembles the typed project context the validator rules read.
+ *
+ * After D-092 this is a pure mapping, not a parser: the caller hands in the effective
+ * (post-patch) Analysis and optionally the pre-patch one, and the facts are projected onto
+ * the validator's contract. The only bytes read here are package.json and tsconfig.json
+ * (installed packages and path aliases), which the analyzer does not model as facts.
+ * Everything is browser-safe.
+ */
+
+import { factsFromManifest } from "./manifest-facts.ts";
+import { normalizeProjectPath, SCHEMA_PATH } from "./paths.ts";
+import type {
+  Analysis,
+  BlockFacts,
+  ConfigFacts,
+  ImportAlias,
+  ProjectContext,
+  ProjectContextInput,
+  RouteFact,
+  TableFact,
+} from "./types.ts";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function normalizeSources(
+  sources: Readonly<Record<string, string>> | undefined,
+): Record<string, string> {
+  const normalized: Record<string, string> = {};
+  for (const [path, content] of Object.entries(sources ?? {})) {
+    normalized[normalizeProjectPath(path)] = content;
+  }
+  return normalized;
+}
+
+function parseJsonRecord(text: string): Record<string, unknown> | null {
+  try {
+    const parsed: unknown = JSON.parse(text);
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Installed bare specifiers from the project's package.json. */
+function packagesFromSource(source: string | undefined): string[] {
+  if (source === undefined) return [];
+  const parsed = parseJsonRecord(source);
+  if (parsed === null) return [];
+  const names = new Set<string>();
+  for (const field of ["dependencies", "devDependencies", "peerDependencies"]) {
+    const section = parsed[field];
+    if (!isRecord(section)) continue;
+    for (const name of Object.keys(section)) names.add(name);
+  }
+  return [...names];
+}
+
+/** `tsconfig.json` `paths` aliases, normalized to project-relative targets. */
+function aliasesFromSource(source: string | undefined): ImportAlias[] {
+  const aliases: ImportAlias[] = [{ prefix: "~/", target: "" }];
+  if (source === undefined) return aliases;
+  const parsed = parseJsonRecord(source);
+  const options =
+    parsed !== null && isRecord(parsed.compilerOptions) ? parsed.compilerOptions : null;
+  const paths = options !== null && isRecord(options.paths) ? options.paths : null;
+  if (paths === null) return aliases;
+  for (const [pattern, targets] of Object.entries(paths)) {
+    if (!Array.isArray(targets) || targets.length === 0) continue;
+    const target = targets[0];
+    if (typeof target !== "string") continue;
+    const prefix = pattern.endsWith("*") ? pattern.slice(0, -1) : pattern;
+    const resolved = target.replace(/^\.\//, "").replace(/\*$/, "").replace(/\/$/, "");
+    aliases.push({ prefix, target: resolved });
+  }
+  return aliases;
+}
+
+/**
+ * The default-locale catalogue: the analyzer's facts first, the manifest only underneath
+ * as a fallback. `analysis.locales.en` is the generated project's source of truth; when
+ * the project's default locale is not English, its catalogue is the next best fact.
+ */
+function flattenCatalog(analysis: Analysis, config: ConfigFacts): Record<string, string> {
+  const defaultLocale = config.defaultLocale ?? "en";
+  const analyzerCatalog =
+    analysis.locales["en"] ?? analysis.locales[defaultLocale] ?? ({} as Record<string, string>);
+  return { ...analyzerCatalog };
+}
+
+/** Build the typed context from analyzer facts; the manifest only contributes fallbacks. */
+export function buildProjectContext(input: ProjectContextInput): ProjectContext {
+  const sources = normalizeSources(input.sources);
+  const manifest = factsFromManifest(input.manifest);
+  const analysis = input.analysis;
+  const before = input.before ?? analysis;
+  const config = analysis.config;
+  const analyzerCatalog = flattenCatalog(analysis, config);
+  const locales: Record<string, string> = { ...manifest.locales, ...analyzerCatalog };
+  const blocks: readonly BlockFacts[] = manifest.blocks;
+  const routes: readonly RouteFact[] = analysis.routes;
+  const tables: readonly TableFact[] = analysis.tables;
+  return {
+    files: input.files.map(normalizeProjectPath).filter((path) => path.length > 0),
+    analysis,
+    before,
+    config,
+    schema: { parsed: analysis.files.includes(SCHEMA_PATH), tables },
+    locales,
+    blocks,
+    routes,
+    packages: input.packages ?? packagesFromSource(sources["package.json"]),
+    aliases: input.aliases ?? aliasesFromSource(sources["tsconfig.json"]),
+  };
+}

package/src/index.ts

@@ -0,0 +1,44 @@
+/**
+ * @facilis.dev/ai — the SPEC §9.3 patch validator and the contracts it shares with the IDE
+ * chat (patches, findings, project context).
+ *
+ * This entry must stay browser-safe: no TypeScript/oxc parser, no Node builtin, no
+ * filesystem. Rule 1's parser is injected as a {@link SyntaxChecker} (the IDE passes the
+ * analyzer worker's oxc parser; Node tooling imports the `@facilis.dev/ai/node` subpath, the
+ * only module that imports a parser). Project facts come from @facilis.dev/analyze's Analysis,
+ * which the caller builds from the VFS file map; analyzer imports here are type-only except
+ * the route-description rule's shared character limit (D-129), a plain constant with no
+ * parser or Node dependency, so nothing heavy is bundled into the IDE.
+ */
+
+export { buildProjectContext } from "./context.ts";
+export { checkPatchSyntax } from "./syntax-runner.ts";
+export type {
+  Analysis,
+  BlockFacts,
+  ColumnFact,
+  ConfigFacts,
+  Diagnostic,
+  FileFacts,
+  FilePatch,
+  ImportAlias,
+  ImportFact,
+  LocaleCatalogs,
+  PatchContext,
+  ProjectContext,
+  ProjectContextInput,
+  RouteFact,
+  SchemaSummary,
+  SourceRef,
+  SyntaxCheck,
+  SyntaxChecker,
+  SyntaxFinding,
+  SyntaxIssue,
+  TableFact,
+  TranslationCallFact,
+  ValidatePatchOptions,
+  ValidationError,
+  ValidationResult,
+  WritePolicy,
+} from "./types.ts";
+export { validatePatch } from "./validator.ts";