@facilis.dev/ai 0.0.0-stage → 0.1.0

package/dist/rules/route-relations.js

@@ -0,0 +1,113 @@
+/**
+ * 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).
+ */
+function lineOf(source) {
+    return source?.line;
+}
+function error(file, message, fixHint, line) {
+    return {
+        rule: "route-table-declared",
+        severity: "error",
+        file,
+        message,
+        fix_hint: fixHint,
+        ...(line === undefined ? {} : { line }),
+    };
+}
+function unusedWarning(route, name) {
+    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) {
+    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) {
+    return (usage.opaque ||
+        usage.rawSql.length > 0 ||
+        usage.elevations.some((elevation) => elevation.opaque || elevation.tablesUnknown));
+}
+/** Rule 18 over the effective analysis (SPEC §9.3, D-157). */
+export function routeTableDeclaredFindings(state) {
+    const errors = [];
+    const warnings = [];
+    for (const route of state.analysis.routes) {
+        // A hand-built analysis may predate the fact (IDE snapshots): no usage facts, no check.
+        const usage = 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/dist/rules/routes-description.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 type { EffectiveState } from "../overlay.js";
+import type { ValidationError } from "../types.js";
+/** Rule 17: every patched route should carry one current English description. */
+export declare function routeDescriptionWarnings(state: EffectiveState): ValidationError[];

package/dist/rules/routes-description.js

@@ -0,0 +1,86 @@
+/**
+ * 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 { normalizeProjectPath } from "../paths.js";
+import { patchedRoutes } from "./routes-security.js";
+const RULE = "route-description";
+function warning(route, message, fix_hint) {
+    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) {
+    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) {
+    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, route) {
+    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) {
+    const warnings = [];
+    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;
+}

package/dist/rules/routes-metadata.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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.js";
+import type { ValidationError } from "../types.js";
+/** Rule 4: every declared `dbTables` entry must be a table or view the project declares. */
+export declare function routeDbTablesErrors(state: EffectiveState): ValidationError[];
+/** Rule 5: `dbColumns` entries are `table.property` references into the effective schema. */
+export declare function routeDbColumnsWarnings(state: EffectiveState): ValidationError[];
+/** Rule 6: every route permission must be declared in `facilis.config.ts`; null fails closed. */
+export declare function permissionErrors(state: EffectiveState): ValidationError[];

package/dist/rules/routes-metadata.js

@@ -0,0 +1,169 @@
+/**
+ * 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 { normalizeProjectPath } from "../paths.js";
+import { patchedRoutes } from "./routes-security.js";
+const COLUMN_REFERENCE = /^[A-Za-z_$][\w$]*\.[A-Za-z_$][\w$]*$/;
+function tableLookup(tables) {
+    const lookup = new Map();
+    for (const table of tables) {
+        lookup.set(table.name, table);
+        if (table.binding !== null)
+            lookup.set(table.binding, table);
+    }
+    return lookup;
+}
+function untouchedByPatch(route, state) {
+    const file = normalizeProjectPath(route.sourceFile);
+    return !state.patchedPaths.has(file) && !state.deletedPaths.has(file);
+}
+function routeLabel(route) {
+    return route.method + " " + route.path;
+}
+function error(rule, file, message, fix_hint, line) {
+    return {
+        rule,
+        severity: "error",
+        file,
+        message,
+        fix_hint,
+        ...(line === undefined ? {} : { line }),
+    };
+}
+function warning(rule, file, message, fix_hint, line) {
+    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) {
+    // 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 = [];
+    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) {
+    const before = new Map(state.beforeSchemaTables.map((table) => [table.name, table]));
+    const removed = [];
+    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) {
+    const lookup = tableLookup(state.schemaTables);
+    const warnings = [];
+    const warn = (file, message, fix_hint, line) => {
+        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) {
+    const declared = new Set(state.config.permissions);
+    const errors = [];
+    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/dist/rules/routes-security.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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.js";
+import type { RouteFact, ValidationError } from "../types.js";
+/** Routes whose source file the patch creates or updates (deleted files have no facts). */
+export declare function patchedRoutes(state: EffectiveState): RouteFact[];
+/** Rule 2: the default export must be the resolved `defineAuthorizedHandler` call. */
+export declare function routeSecurityErrors(state: EffectiveState): ValidationError[];
+/** Rule 3: `dbTables` must be present; unknown (null) fails closed. */
+export declare function routeDbTablesPresentErrors(state: EffectiveState): ValidationError[];
+/**
+ * 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 declare function routeInputErrors(state: EffectiveState): ValidationError[];

package/dist/rules/routes-security.js

@@ -0,0 +1,52 @@
+/**
+ * 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 { normalizeProjectPath } from "../paths.js";
+/** Routes whose source file the patch creates or updates (deleted files have no facts). */
+export function patchedRoutes(state) {
+    return state.analysis.routes.filter((route) => state.patchedPaths.has(normalizeProjectPath(route.sourceFile)));
+}
+function error(rule, route, message, fix_hint) {
+    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) {
+    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) {
+    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) {
+    return patchedRoutes(state).flatMap((route) => {
+        const errors = [];
+        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/dist/rules/structural.d.ts

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

package/dist/rules/structural.js

@@ -0,0 +1,33 @@
+/**
+ * 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.js";
+const UNSAFE_SEGMENTS = new Set(["..", "."]);
+function error(rule, file, message, fix_hint) {
+    return { rule, severity: "error", file, message, fix_hint };
+}
+export function structuralErrors(patches, allowedRootFiles = []) {
+    const errors = [];
+    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/dist/rules/ts-parse.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 type { FilePatch, SyntaxCheck, ValidationError } from "../types.js";
+export interface ScriptSource {
+    path: string;
+    content: string;
+}
+/** Create/update patches that carry a script file, in patch order. */
+export declare function scriptSources(patches: readonly FilePatch[]): ScriptSource[];
+export declare function tsParseErrors(patches: readonly FilePatch[], syntax: SyntaxCheck): ValidationError[];

package/dist/rules/ts-parse.js

@@ -0,0 +1,62 @@
+/**
+ * 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.js";
+/** Create/update patches that carry a script file, in patch order. */
+export function scriptSources(patches) {
+    const sources = [];
+    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, line) {
+    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, syntax) {
+    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 = [];
+    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/dist/syntax-runner.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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 type { FilePatch, SyntaxChecker, SyntaxFinding } from "./types.js";
+export declare function checkPatchSyntax(patches: readonly FilePatch[], checker: SyntaxChecker): Promise<SyntaxFinding[]>;

package/dist/syntax-runner.js

@@ -0,0 +1,25 @@
+/**
+ * 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.js";
+export async function checkPatchSyntax(patches, checker) {
+    const checked = await Promise.all(scriptSources(patches).map(async (source) => ({
+        source,
+        issues: await checker.check(source.path, source.content),
+    })));
+    const findings = [];
+    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;
+}