@descryy/core 0.3.0 → 0.5.0

package/dist/sources/migrations/across-change.js

@@ -0,0 +1,278 @@
+/**
+ * §14.6 for one change against a base branch — the shape `cross_pr` actually has.
+ *
+ * ## Why the base branch is the second member of the set
+ *
+ * `migration-heads.ts` computes heads across a *set of changes*, and `cross_pr`
+ * has one. That is not a mismatch, it is a missing member: the set the
+ * migration runner will see after this merge is **base's migrations plus this
+ * change's**, and heads over that union is exactly the computation the runner
+ * performs when it refuses with *"multiple head revisions are present"*.
+ *
+ * So base is read as a change with its own id. Nothing about the check changes;
+ * it is given the set it was always meant to have.
+ *
+ * ## The one wrong sentence this must not say
+ *
+ * A base branch that already forks produces two heads whatever the change does.
+ * Reporting that as *this* change's conflict is a wrong sentence about the wrong
+ * person, and it would fire on every change to such a repository until someone
+ * fixed a fork they did not create.
+ *
+ * So base is measured **alone** first. Its head count is a fact about base:
+ *
+ * | base alone | what this reports |
+ * | --- | --- |
+ * | one head | the union is computed and `baseHead` is supplied, so stale-history is checked too |
+ * | more than one | a disclosure naming base's fork, and no conflict attributed to the change |
+ * | none — no migrations at all | the change's own migrations, with nothing to fork from |
+ *
+ * ## Reading base without checking it out
+ *
+ * `git ls-tree` names base's files and `git show base:<path>` reads one. Neither
+ * touches the working tree, so this is safe to run mid-edit — which is the only
+ * time anyone runs a pre-merge check.
+ *
+ * The tree is narrowed by {@link looksLikeMigration} before anything is read. A
+ * base branch is thousands of paths and its migrations are dozens; reading all
+ * of them to discover that would be the check's whole cost paid for nothing.
+ *
+ * ## Everything here is R0 and the ceiling follows
+ *
+ * A regex over source text, per `read.ts`. The class column is a ceiling rather
+ * than a floor, so a conflict computed from these records caps at C however
+ * certain the arithmetic above it. Reaching A needs the framework's own
+ * migration history, which needs the tool installed and run, and nothing here
+ * installs or runs anything.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { cleanGitEnv } from "../git/env.js";
+import { findMigrationHeadConflicts } from "../../multipr/migration-heads.js";
+import { readMigrations, looksLikeMigration } from "./read.js";
+import { DIALECTS } from "./dialects.js";
+const execFileAsync = promisify(execFile);
+/**
+ * Cap on migration files read from either side.
+ *
+ * A repository with more migrations than this exists, and reading all of them
+ * is a subprocess each. Truncation is disclosed and the report is marked
+ * incomplete rather than being presented as a full head computation.
+ */
+const MAX_FILES = 400;
+/**
+ * How many misplaced-looking files in one directory stop being mistakes.
+ *
+ * A project can configure a second version location this producer's globs do
+ * not recognise, and one file at a time that is indistinguishable from a stray.
+ * In bulk it is not: a stray sits alone, a configured directory holds a pile.
+ * So the rule is about the directory rather than the file, and a directory at
+ * or above this count is disclosed rather than reported.
+ *
+ * Three is a starting value, not a measurement.
+ */
+const SECOND_LOCATION_CLUSTER = 3;
+async function git(cwd, args) {
+    const { stdout } = await execFileAsync("git", args, {
+        cwd,
+        encoding: "utf8",
+        env: cleanGitEnv(),
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    return stdout;
+}
+/**
+ * Migrations that parse but sit where nothing will run them.
+ *
+ * One `git grep` per probing dialect rather than a walk: the whole tree is
+ * searched in one indexed subprocess, and only the files it names are read.
+ * Reading every source file to find out it is not a migration is the cost this
+ * check would otherwise pay on every run.
+ *
+ * Guarded twice, because the failure to avoid is telling a project its own
+ * layout is wrong:
+ *
+ *  1. **The dialect must already be in use** somewhere this producer
+ *     recognises. With no recognised migrations there is nothing to be outside
+ *     of, and a project keeping them somewhere unknown is not a project with a
+ *     misplaced file.
+ *  2. **A directory holding several is a location, not a pile of mistakes** —
+ *     see {@link SECOND_LOCATION_CLUSTER}. Disclosed rather than reported.
+ */
+async function findMisplaced(cwd, rev, recognised, read, notes) {
+    const out = [];
+    for (const dialect of DIALECTS) {
+        if (dialect.probe === undefined)
+            continue;
+        // Guard 1: this dialect has to be in use here already.
+        if (!recognised.some((path) => looksLikeMigration(path)))
+            continue;
+        let hits;
+        try {
+            const stdout = await git(cwd, ["grep", "-l", "-E", dialect.probe, rev]);
+            hits = stdout
+                .split("\n")
+                .map((line) => line.trim())
+                .filter((line) => line !== "")
+                // `git grep <rev>` prefixes every path with `<rev>:`.
+                .map((line) => (line.startsWith(`${rev}:`) ? line.slice(rev.length + 1) : line))
+                .filter((path) => !looksLikeMigration(path));
+        }
+        catch {
+            // git grep exits non-zero when nothing matches. No hits is the answer.
+            continue;
+        }
+        if (hits.length === 0)
+            continue;
+        // Guard 2: group by directory before deciding anything.
+        const byDirectory = new Map();
+        for (const path of hits) {
+            const dir = path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : ".";
+            const bucket = byDirectory.get(dir);
+            if (bucket === undefined)
+                byDirectory.set(dir, [path]);
+            else
+                bucket.push(path);
+        }
+        for (const [dir, paths] of [...byDirectory].sort(([a], [b]) => a.localeCompare(b))) {
+            if (paths.length >= SECOND_LOCATION_CLUSTER) {
+                notes.push(`${paths.length} files in ${dir} parse as ${dialect.displayName} migrations and are ` +
+                    "not in a location this producer recognises. That many together reads as a second " +
+                    "configured version location rather than as that many mistakes, so they are " +
+                    "disclosed here and not reported as findings — and they are not in the head " +
+                    "computation either.");
+                continue;
+            }
+            for (const path of paths) {
+                const text = await read(path);
+                if (text === null)
+                    continue;
+                // Confirmed with the real reader, never from the grep hit alone: the
+                // probe finds a candidate and the parser decides whether it is one.
+                //
+                // The reader selects a dialect by path and this path is, by definition,
+                // one no dialect claims — so it is offered a synthetic path under a
+                // recognised directory. The content is the file's own and unmodified;
+                // only the question changes, from "is there a migration here?" to
+                // "would this parse as one if it were where it belongs?". The real path
+                // is what the finding reports.
+                const name = path.slice(path.lastIndexOf("/") + 1);
+                const report = readMigrations(rev, [`versions/${name}`], { read: () => text });
+                const record = report.records[0];
+                if (record === undefined)
+                    continue;
+                out.push({ file: path, revision: record.revision, dialect: dialect.id });
+            }
+        }
+    }
+    return out;
+}
+/** Every migration-shaped path in one revision's tree. */
+async function migrationPathsIn(cwd, rev) {
+    const stdout = await git(cwd, ["ls-tree", "-r", "--name-only", rev]);
+    return stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line !== "" && looksLikeMigration(line));
+}
+/** Heads of a record set: revisions nothing else in the set descends from. */
+function headsOf(report) {
+    const claimed = new Set();
+    for (const record of report.records) {
+        if (record.parents === "unknown")
+            continue;
+        for (const parent of record.parents)
+            claimed.add(parent);
+    }
+    return report.records.map((r) => r.revision).filter((revision) => !claimed.has(revision));
+}
+/**
+ * Read both sides of a merge and compute the heads it would leave.
+ *
+ * @param base the branch this change would merge into
+ * @param head the tip being reviewed
+ */
+export async function readMigrationsAcrossChange(cwd, base, head, options = {}) {
+    const maxFiles = options.maxFiles ?? MAX_FILES;
+    const notes = [];
+    const changed = options.changedFiles ??
+        (await git(cwd, ["diff", "--name-only", "-M", `${base}...${head}`]))
+            .split("\n")
+            .map((l) => l.trim())
+            .filter((l) => l !== "");
+    const changedMigrations = changed.filter(looksLikeMigration);
+    // Base's own migrations, minus anything this change also touches: a file on
+    // both sides is the change's, and counting it twice would mint two records
+    // for one revision and report a duplicate identifier that does not exist.
+    const touched = new Set(changedMigrations);
+    const basePaths = (await migrationPathsIn(cwd, base)).filter((p) => !touched.has(p));
+    const cap = (paths, side) => {
+        if (paths.length <= maxFiles)
+            return paths;
+        notes.push(`${paths.length} migration file(s) are on ${side} and only ${maxFiles} were read. The head ` +
+            "computation below covers a prefix of them rather than all of them, so it is not a " +
+            "complete answer — an unread migration may be exactly the merge that resolves a fork.");
+        return paths.slice(0, maxFiles);
+    };
+    const contents = async (rev, paths) => {
+        const out = new Map();
+        for (const path of paths) {
+            try {
+                out.set(path, await git(cwd, ["show", `${rev}:${path}`]));
+            }
+            catch {
+                // Left absent. `readMigrations` records the failure as a refusal row.
+            }
+        }
+        return out;
+    };
+    const baseRead = cap(basePaths, `\`${base}\``);
+    const changePaths = cap(changedMigrations, "this change");
+    const baseText = await contents(base, baseRead);
+    const changeText = await contents(head, changePaths);
+    const reader = (map) => (path) => {
+        const text = map.get(path);
+        if (text === undefined)
+            throw new Error("not present in that revision");
+        return text;
+    };
+    const baseReport = readMigrations(base, baseRead, { read: reader(baseText) });
+    const changeReport = readMigrations(head, changePaths, { read: reader(changeText) });
+    // Base measured alone, so a fork it already has is never attributed here.
+    const baseHeads = headsOf(baseReport);
+    let baseHead = null;
+    if (baseHeads.length === 1)
+        baseHead = baseHeads[0];
+    else if (baseHeads.length > 1) {
+        notes.push(`The base branch already has ${baseHeads.length} migration heads before this change: ` +
+            `${baseHeads.join(", ")}. That fork is not this change's, so no conflict is attributed ` +
+            "to it here and the merged head count is not reported as a finding.");
+    }
+    const union = [...baseReport.records, ...changeReport.records];
+    const report = baseHeads.length > 1
+        ? // Base is already forked. Compute the change's own migrations against
+            // each other so a fork *within* the change is still caught, and leave
+            // base out of the head count entirely.
+            findMigrationHeadConflicts(changeReport.records)
+        : findMigrationHeadConflicts(union, ...(baseHead === null ? [] : [{ baseHead }]));
+    // Searched on `head`, because that is the tree about to be merged. A file
+    // misplaced on base and left alone by this change is still misplaced, and the
+    // developer pushing is the one who can see it.
+    const misplaced = await findMisplaced(cwd, head, [...basePaths, ...changedMigrations], async (path) => {
+        try {
+            return await git(cwd, ["show", `${head}:${path}`]);
+        }
+        catch {
+            return null;
+        }
+    }, notes);
+    return {
+        base: baseReport,
+        change: changeReport,
+        baseHead,
+        report,
+        misplaced,
+        notes: [...notes, ...report.notes],
+    };
+}
+//# sourceMappingURL=across-change.js.map

package/dist/sources/migrations/across-change.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"across-change.js","sourceRoot":"","sources":["../../../src/sources/migrations/across-change.ts"],"names":[],"mappings":"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"}

package/dist/sources/migrations/dialects.d.ts

@@ -1,33 +1,8 @@
-/**
- * The dialect table — the only place in `descry-core` that describes a migration
- * file format, and it does so **without naming a single tool**.
- *
- * That is not a dodge around the boundary lint; it is the design the lint is a
- * proxy for. Rule 1 forbids a language or framework name above the Canonical IR.
- * A migration-file reader is a producer and sits below it — exactly like
- * `sources/git` and like an adapter — so naming a tool here would be defensible.
- * It turned out not to be necessary: every distinction §14.6 needs is a
- * distinction about **shape**, and a table written in shapes is one an unfamiliar
- * reader can check against a file without knowing which ecosystem it came from.
- *
- * The consequence worth having is that `read.ts` knows nothing but this table, so
- * **adding a dialect is a data change and never a code change**.
- *
- * `parentsKind` names a shape:
- *
- * | kind | the captured expression is |
- * | --- | --- |
- * | `single-or-none` | one quoted id, a null literal, or a tuple for a merge |
- * | `id-list` | a bracketed list of quoted ids |
- * | `pair-list` | a bracketed list of two-element tuples, joined with `/` |
- *
- * Every dialect here is **R0** — a regex over source text. DEC-058 and §15.3: a
- * record carries the resolution of its own evidence, so a head conflict computed
- * from these caps at class C however certain the arithmetic on top of it. Class A
- * needs the framework's own migration history, which is DEC-115's promotion path
- * and needs the tool installed and run. **Nothing here installs or runs
- * anything.**
- */
+/** Migration dialect table — no tool named (rule 1: this producer sits
+ *  below the IR, but every distinction §14.6 needs is about shape, so a
+ *  tool name was never necessary). Adding a dialect is a data change, not
+ *  code. All R0 (regex over text) — DEC-058/§15.3 caps a resulting
+ *  conflict at class C; class A needs the tool's own history (DEC-115). */
 export type ParentsKind = "single-or-none" | "id-list" | "pair-list";
 export interface Dialect {
     readonly id: string;
@@ -41,6 +16,19 @@ export interface Dialect {
     readonly parentsKind: ParentsKind;
     /** A second, additive predecessor channel where the format has one. */
     readonly alsoParents?: string;
+    /**
+     * A POSIX ERE `git grep` can run to find candidate files **by content**,
+     * anywhere in a tree, for the misplaced-migration check.
+     *
+     * Separate from `parents` rather than derived from it: that pattern is
+     * JavaScript-flavoured and this one is handed to another program. Optional
+     * on purpose — a dialect whose marker is not distinctive enough to survive a
+     * whole-repository grep declares none, and is simply not searched for. The
+     * dependency-list dialect is the case: `dependencies = [` appears in
+     * packaging metadata across most of the ecosystem, so grepping for it would
+     * return a repository's build files and call them migrations.
+     */
+    readonly probe?: string;
     readonly why: string;
 }
 export interface RefusedFamily {
@@ -49,11 +37,7 @@ export interface RefusedFamily {
     readonly why: string;
 }
 export declare const DIALECTS: readonly Dialect[];
-/**
- * Families this producer declines, by design rather than by failure.
- *
- * The refusal is the interesting half of this table, so it is data too — a
- * refused file produces a row carrying this sentence, not a silence.
- */
+/** Families this producer declines, by design not failure — the refusal
+ *  is data too: a refused file gets this sentence, not silence. */
 export declare const REFUSED: readonly RefusedFamily[];
 //# sourceMappingURL=dialects.d.ts.map

package/dist/sources/migrations/dialects.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dialects.d.ts","sourceRoot":"","sources":["../../../src/sources/migrations/dialects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,MAAM,MAAM,WAAW,GAAG,gBAAgB,GAAG,SAAS,GAAG,WAAW,CAAC;AAErE,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,uEAAuE;IACvE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,QAAQ,EAAE,SAAS,OAAO,EAyBtC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,OAAO,EAAE,SAAS,aAAa,EAuB3C,CAAC"}
+{"version":3,"file":"dialects.d.ts","sourceRoot":"","sources":["../../../src/sources/migrations/dialects.ts"],"names":[],"mappings":"AAAA;;;;2EAI2E;AAE3E,MAAM,MAAM,WAAW,GAAG,gBAAgB,GAAG,SAAS,GAAG,WAAW,CAAC;AAErE,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,uEAAuE;IACvE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,QAAQ,EAAE,SAAS,OAAO,EA6BtC,CAAC;AAEF;mEACmE;AACnE,eAAO,MAAM,OAAO,EAAE,SAAS,aAAa,EAuB3C,CAAC"}

package/dist/sources/migrations/dialects.js

@@ -1,33 +1,8 @@
-/**
- * The dialect table — the only place in `descry-core` that describes a migration
- * file format, and it does so **without naming a single tool**.
- *
- * That is not a dodge around the boundary lint; it is the design the lint is a
- * proxy for. Rule 1 forbids a language or framework name above the Canonical IR.
- * A migration-file reader is a producer and sits below it — exactly like
- * `sources/git` and like an adapter — so naming a tool here would be defensible.
- * It turned out not to be necessary: every distinction §14.6 needs is a
- * distinction about **shape**, and a table written in shapes is one an unfamiliar
- * reader can check against a file without knowing which ecosystem it came from.
- *
- * The consequence worth having is that `read.ts` knows nothing but this table, so
- * **adding a dialect is a data change and never a code change**.
- *
- * `parentsKind` names a shape:
- *
- * | kind | the captured expression is |
- * | --- | --- |
- * | `single-or-none` | one quoted id, a null literal, or a tuple for a merge |
- * | `id-list` | a bracketed list of quoted ids |
- * | `pair-list` | a bracketed list of two-element tuples, joined with `/` |
- *
- * Every dialect here is **R0** — a regex over source text. DEC-058 and §15.3: a
- * record carries the resolution of its own evidence, so a head conflict computed
- * from these caps at class C however certain the arithmetic on top of it. Class A
- * needs the framework's own migration history, which is DEC-115's promotion path
- * and needs the tool installed and run. **Nothing here installs or runs
- * anything.**
- */
+/** Migration dialect table — no tool named (rule 1: this producer sits
+ *  below the IR, but every distinction §14.6 needs is about shape, so a
+ *  tool name was never necessary). Adding a dialect is a data change, not
+ *  code. All R0 (regex over text) — DEC-058/§15.3 caps a resulting
+ *  conflict at class C; class A needs the tool's own history (DEC-115). */
 export const DIALECTS = [
     {
         id: "revision-chain",
@@ -37,6 +12,10 @@ export const DIALECTS = [
         parents: "^\\s*down_revision(?:\\s*:\\s*[^=]+)?\\s*=\\s*(.+)$",
         parentsKind: "single-or-none",
         alsoParents: "^\\s*depends_on(?:\\s*:\\s*[^=]+)?\\s*=\\s*(.+)$",
+        // Distinctive enough for a whole-repository search: a module-level
+        // `down_revision` binding exists to name a migration's parent and has no
+        // second meaning.
+        probe: "^[[:space:]]*down_revision[[:space:]]*[:=]",
         why: "Each revision names exactly one predecessor, or a null literal for the root; a merge " +
             "revision names a tuple. A declared DAG, and the tool itself refuses to run with more " +
             "than one head — which is the failure §14.6 predicts.",
@@ -52,12 +31,8 @@ export const DIALECTS = [
             "and the tool detects conflicting leaves by name.",
     },
 ];
-/**
- * Families this producer declines, by design rather than by failure.
- *
- * The refusal is the interesting half of this table, so it is data too — a
- * refused file produces a row carrying this sentence, not a silence.
- */
+/** Families this producer declines, by design not failure — the refusal
+ *  is data too: a refused file gets this sentence, not silence. */
 export const REFUSED = [
     {
         id: "timestamp-ordered-directory",

package/dist/sources/migrations/dialects.js.map

@@ -1 +1 @@
-{"version":3,"file":"dialects.js","sourceRoot":"","sources":["../../../src/sources/migrations/dialects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAyBH,MAAM,CAAC,MAAM,QAAQ,GAAuB;IAC1C;QACE,EAAE,EAAE,gBAAgB;QACpB,WAAW,EAAE,8BAA8B;QAC3C,KAAK,EAAE,CAAC,kBAAkB,EAAE,6BAA6B,CAAC;QAC1D,QAAQ,EAAE,4DAA4D;QACtE,OAAO,EAAE,qDAAqD;QAC9D,WAAW,EAAE,gBAAgB;QAC7B,WAAW,EAAE,kDAAkD;QAC/D,GAAG,EACD,uFAAuF;YACvF,uFAAuF;YACvF,sDAAsD;KACzD;IACD;QACE,EAAE,EAAE,iBAAiB;QACrB,WAAW,EAAE,iBAAiB;QAC9B,KAAK,EAAE,CAAC,oBAAoB,CAAC;QAC7B,oBAAoB,EAAE,sBAAsB;QAC5C,OAAO,EAAE,yCAAyC;QAClD,WAAW,EAAE,WAAW;QACxB,GAAG,EACD,yFAAyF;YACzF,kDAAkD;KACrD;CACF,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GAA6B;IAC/C;QACE,EAAE,EAAE,6BAA6B;QACjC,KAAK,EAAE,CAAC,8BAA8B,EAAE,oBAAoB,CAAC;QAC7D,GAAG,EACD,sFAAsF;YACtF,wFAAwF;YACxF,mFAAmF;YACnF,oFAAoF;YACpF,wFAAwF;YACxF,yFAAyF;YACzF,qFAAqF;YACrF,gEAAgE;YAChE,yFAAyF;YACzF,mFAAmF;YACnF,0FAA0F;YAC1F,sFAAsF;YACtF,wFAAwF;YACxF,wFAAwF;YACxF,sFAAsF;YACtF,qFAAqF;YACrF,uEAAuE;KAC1E;CACF,CAAC"}
+{"version":3,"file":"dialects.js","sourceRoot":"","sources":["../../../src/sources/migrations/dialects.ts"],"names":[],"mappings":"AAAA;;;;2EAI2E;AAsC3E,MAAM,CAAC,MAAM,QAAQ,GAAuB;IAC1C;QACE,EAAE,EAAE,gBAAgB;QACpB,WAAW,EAAE,8BAA8B;QAC3C,KAAK,EAAE,CAAC,kBAAkB,EAAE,6BAA6B,CAAC;QAC1D,QAAQ,EAAE,4DAA4D;QACtE,OAAO,EAAE,qDAAqD;QAC9D,WAAW,EAAE,gBAAgB;QAC7B,WAAW,EAAE,kDAAkD;QAC/D,mEAAmE;QACnE,yEAAyE;QACzE,kBAAkB;QAClB,KAAK,EAAE,4CAA4C;QACnD,GAAG,EACD,uFAAuF;YACvF,uFAAuF;YACvF,sDAAsD;KACzD;IACD;QACE,EAAE,EAAE,iBAAiB;QACrB,WAAW,EAAE,iBAAiB;QAC9B,KAAK,EAAE,CAAC,oBAAoB,CAAC;QAC7B,oBAAoB,EAAE,sBAAsB;QAC5C,OAAO,EAAE,yCAAyC;QAClD,WAAW,EAAE,WAAW;QACxB,GAAG,EACD,yFAAyF;YACzF,kDAAkD;KACrD;CACF,CAAC;AAEF;mEACmE;AACnE,MAAM,CAAC,MAAM,OAAO,GAA6B;IAC/C;QACE,EAAE,EAAE,6BAA6B;QACjC,KAAK,EAAE,CAAC,8BAA8B,EAAE,oBAAoB,CAAC;QAC7D,GAAG,EACD,sFAAsF;YACtF,wFAAwF;YACxF,mFAAmF;YACnF,oFAAoF;YACpF,wFAAwF;YACxF,yFAAyF;YACzF,qFAAqF;YACrF,gEAAgE;YAChE,yFAAyF;YACzF,mFAAmF;YACnF,0FAA0F;YAC1F,sFAAsF;YACtF,wFAAwF;YACxF,wFAAwF;YACxF,sFAAsF;YACtF,qFAAqF;YACrF,uEAAuE;KAC1E;CACF,CAAC"}

package/dist/sources/migrations/index.d.ts

@@ -1,3 +1,5 @@
-export { readMigrations, DIALECTS, REFUSED } from "./read.ts";
+export { readMigrations, looksLikeMigration, DIALECTS, REFUSED } from "./read.ts";
+export { readMigrationsAcrossChange } from "./across-change.ts";
+export type { MigrationsAcrossChange, AcrossChangeOptions } from "./across-change.ts";
 export type { Dialect, RefusedFamily, MigrationRefusal, MigrationReadReport, ParentsKind, ReadOptions, } from "./read.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/sources/migrations/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sources/migrations/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC9D,YAAY,EACV,OAAO,EACP,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACnB,WAAW,EACX,WAAW,GACZ,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sources/migrations/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAClF,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAChE,YAAY,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACtF,YAAY,EACV,OAAO,EACP,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACnB,WAAW,EACX,WAAW,GACZ,MAAM,WAAW,CAAC"}

package/dist/sources/migrations/index.js

@@ -1,2 +1,3 @@
-export { readMigrations, DIALECTS, REFUSED } from "./read.js";
+export { readMigrations, looksLikeMigration, DIALECTS, REFUSED } from "./read.js";
+export { readMigrationsAcrossChange } from "./across-change.js";
 //# sourceMappingURL=index.js.map

package/dist/sources/migrations/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/sources/migrations/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/sources/migrations/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAClF,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/sources/migrations/read.d.ts

@@ -1,70 +1,7 @@
 /**
- * The producer `migration-heads.ts` has been waiting for.
- *
- * §14.6's check is built, exposed through the MCP tool, and **nothing fed it**.
- * It has been recommended four times and declined once. This is the feed.
- *
- * ## What it will and will not read
- *
- * `migration-heads.ts` says the input is *"a revision, its declared parents and
- * where it came from — the shape every migration tool has, whatever it calls the
- * fields"*, and it says the reading is producer work. It is right about the
- * shape and it is wrong that every tool has it.
- *
- * **Two of the four common families declare a DAG and two do not**, and the
- * difference is not cosmetic — it decides whether §14.6's finding exists at all:
- *
- * | family | declares | head conflict is |
- * | --- | --- | --- |
- * | revision/down_revision chain | one parent per revision, tuples for merges | a real failure the tool itself raises |
- * | dependency list | `(app, name)` pairs per migration | a real failure the tool itself detects |
- * | **timestamp-ordered directory** | **nothing** | **not a thing that can happen** |
- *
- * The last row covers both of the two frameworks this row named as *"the obvious
- * first two"*. They track applied migrations as a **set** in a table, run
- * whatever is pending in filename order, and have no multiple-head error to
- * predict. Two changes each adding a migration is the normal case and it
- * succeeds.
- *
- * Synthesising `parents = [the previous file by timestamp]` would manufacture
- * exactly the DAG this check consumes — and would then report a conflict for
- * *every* pair of changes that each add a migration, since both would carry the
- * same synthesised parent. A maybe-list built from an invented format, published
- * beside real Class A structural facts and indistinguishable from them in the
- * output.
- *
- * So those files are **refused with a reason**, and the refusal is a row.
- *
- * ## Measured rather than assumed, and the asymmetry is stated
- *
- * 604 migrations across three real applications using the timestamp-ordered
- * pattern: **0 declare a revision id or a parent.** The twelve files that matched
- * `/parent/` matched a `parent_id` column and one comment.
- *
- * The other timestamp-ordered ecosystem is refused on **documented behaviour**,
- * because no corpus using it was available here. That is a weaker basis than the
- * measured one and is labelled as such rather than folded in beside it.
- *
- * ## Everything this produces is R0, and the ceiling follows
- *
- * A regex over source text. §15.2 lists migration head conflict as Class A and
- * §15.3 already settles the disagreement: **the Class column is a ceiling, not a
- * floor.** Per DEC-058 the record carries the resolution of its own evidence, so
- * a conflict computed from these records caps at C however certain the
- * arithmetic above it. Class A needs the framework's own migration history —
- * DEC-115's promotion path — which needs the tool installed and run.
- *
- * **Nothing here installs or runs anything**, by policy: cloned third-party
- * source is arbitrary code and installing it executes it. The cost of that policy
- * is this ceiling, and it is disclosed rather than hidden.
- *
- * ## `"unknown"` is not `[]`, enforced here rather than downstream
- *
- * A migration whose parent line could not be read gets `"unknown"`. An initial
- * migration gets `[]`. `migration-heads.ts` makes the distinction unrepresentable
- * in its type for a reason — an unread migration might be exactly the merge that
- * resolves the fork being reported — and a producer that returns `[]` on a failed
- * match would defeat that from below.
+ * Feeds §14.6's migration head conflict check. Regex over source (R0) caps a conflict at C (DEC-058) —
+ * Class A needs the framework's own tool run (DEC-115), which this never does, by policy. Timestamp-ordered
+ * directories declare no DAG (604 migrations measured, 0 declare a parent) — refused with a reason, never a synthesised fake parent.
  */
 import type { ResolutionLevel } from "@descryy/ir";
 import type { MigrationRecord } from "../../multipr/migration-heads.ts";
@@ -82,13 +19,7 @@ export interface MigrationRefusal {
 export interface MigrationReadReport {
     readonly records: readonly MigrationRecord[];
     readonly refusals: readonly MigrationRefusal[];
-    /**
-     * False when no file matched any dialect at all.
-     *
-     * An empty `records` with `analysed: false` means no migration format was
-     * recognised, not that the change adds no migrations — the same distinction
-     * `hidden-dependency.ts` draws for co-change history, for the same reason.
-     */
+    /** False when no file matched any dialect — not the same as "adds no migrations" (same distinction as `hidden-dependency.ts`). */
     readonly analysed: boolean;
     readonly checked: {
         readonly files: number;
@@ -98,16 +29,20 @@ export interface MigrationReadReport {
         readonly parentsUnknown: number;
     };
 }
+/**
+ * Does any dialect or refused family claim this path?
+ *
+ * Exported so a caller enumerating a whole tree can narrow it before reading
+ * anything. A base branch's full file list is thousands of paths and its
+ * migrations are dozens; reading all of them to discover that would be the
+ * check's cost paid on every run for nothing.
+ */
+export declare const looksLikeMigration: (path: string) => boolean;
 export interface ReadOptions {
     /** Reads the file. Injectable so the whole producer is testable with no disk. */
     readonly read?: (path: string) => string;
     readonly resolution?: ResolutionLevel;
 }
-/**
- * Read every migration a change adds.
- *
- * @param prId whatever identifies the change — passed straight through
- * @param files paths the change added, relative to the repository root
- */
+/** Read every migration a change adds. `files` are paths relative to the repository root. */
 export declare function readMigrations(prId: string, files: readonly string[], options?: ReadOptions): MigrationReadReport;
 //# sourceMappingURL=read.d.ts.map

package/dist/sources/migrations/read.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../../src/sources/migrations/read.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEzE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;AAC7B,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,CAAC;AAEpD,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC/C;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;QACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;KACjC,CAAC;CACH;AAsGD,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACzC,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC;CACvC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,GAAE,WAAgB,GACxB,mBAAmB,CAoGrB"}
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../../src/sources/migrations/read.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEzE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;AAC7B,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,CAAC;AAEpD,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC/C,kIAAkI;IAClI,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;QACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;KACjC,CAAC;CACH;AA4BD;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,OAEF,CAAC;AA2DjD,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACzC,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC;CACvC;AAED,6FAA6F;AAC7F,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,GAAE,WAAgB,GACxB,mBAAmB,CAoGrB"}