@descryy/core 0.1.0

package/dist/sources/migrations/index.js

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

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

@@ -0,0 +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"}

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

@@ -0,0 +1,113 @@
+/**
+ * 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.
+ */
+import type { ResolutionLevel } from "@descryy/ir";
+import type { MigrationRecord } from "../../multipr/migration-heads.ts";
+import { DIALECTS, REFUSED } from "./dialects.ts";
+import type { Dialect, ParentsKind, RefusedFamily } from "./dialects.ts";
+export { DIALECTS, REFUSED };
+export type { Dialect, ParentsKind, RefusedFamily };
+/** One file this producer declined, and why. A refusal is a row, never a silence. */
+export interface MigrationRefusal {
+    readonly file: string;
+    readonly reason: string;
+    /** Set when the file matched a family that is refused by design rather than by failure. */
+    readonly family?: string;
+}
+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.
+     */
+    readonly analysed: boolean;
+    readonly checked: {
+        readonly files: number;
+        readonly matchedDialect: number;
+        readonly matchedRefusedFamily: number;
+        readonly unrecognised: number;
+        readonly parentsUnknown: number;
+    };
+}
+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
+ */
+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

@@ -0,0 +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"}

package/dist/sources/migrations/read.js

@@ -0,0 +1,270 @@
+/**
+ * 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.
+ */
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { DIALECTS, REFUSED } from "./dialects.js";
+export { DIALECTS, REFUSED };
+/**
+ * Glob subset sufficient for these patterns: `**` across directory boundaries,
+ * `*` within one segment.
+ *
+ * Scanned rather than built by chained `replace`. The chained version needs a
+ * placeholder to stop `**` being rewritten by the `*` pass, the placeholder has
+ * to be a character no path contains, and the obvious choice is a raw control
+ * byte — which is exactly how `sources/git/source.ts` came to be binary to git
+ * and grep, found in the same batch of work as this file. A scan has no ordering
+ * problem, so it needs no placeholder, so the question never arises.
+ */
+function globToRegExp(glob) {
+    let out = "";
+    for (let i = 0; i < glob.length; i += 1) {
+        const char = glob[i];
+        if (char !== "*") {
+            out += /[a-zA-Z0-9_-]/.test(char) ? char : `\\${char}`;
+            continue;
+        }
+        if (glob[i + 1] === "*") {
+            // `**/` is any number of directory segments, INCLUDING none — so
+            // `**/versions/*.py` matches `versions/a.py` as well as `x/y/versions/a.py`.
+            if (glob[i + 2] === "/") {
+                out += "(?:[^/]*/)*";
+                i += 2;
+            }
+            else {
+                out += ".*";
+                i += 1;
+            }
+            continue;
+        }
+        out += "[^/]*";
+    }
+    return new RegExp(`^${out}$`);
+}
+const matchesAny = (path, globs) => globs.some((glob) => globToRegExp(glob).test(path));
+/**
+ * Parse the captured right-hand side of a parents declaration.
+ *
+ * Returns `null` when the expression was found but could not be understood —
+ * which becomes `"unknown"`, never `[]`. A null literal is the one case that
+ * legitimately yields the empty list, because a declared root genuinely has no
+ * parent.
+ */
+function parseParents(raw, kind) {
+    const text = raw.trim().replace(/#.*$/, "").trim();
+    // A declared root. The only path from a matched expression to an empty list.
+    if (/^(none|null|nil)$/i.test(text))
+        return [];
+    switch (kind) {
+        case "single-or-none": {
+            const single = /^["']([^"']+)["']/.exec(text);
+            if (single !== null)
+                return [single[1]];
+            // A merge revision names several. Bracketed or parenthesised, both seen.
+            if (/^[([]/.test(text)) {
+                const ids = [...text.matchAll(/["']([^"']+)["']/g)].map((m) => m[1]);
+                return ids.length > 0 ? ids : null;
+            }
+            return null;
+        }
+        case "id-list": {
+            const ids = [...text.matchAll(/["']([^"']+)["']/g)].map((m) => m[1]);
+            return ids.length > 0 ? ids : null;
+        }
+        case "pair-list": {
+            // Two-element tuples. Joined with `/` so a revision id is a single string
+            // at this boundary, which is what MigrationRecord.revision is.
+            const pairs = [
+                ...text.matchAll(/[([]\s*["']([^"']+)["']\s*,\s*["']([^"']+)["']\s*[)\]]/g),
+            ].map((m) => `${m[1]}/${m[2]}`);
+            // An empty list is a declared root here — `dependencies = []` is written
+            // explicitly by the first migration of an application.
+            if (pairs.length === 0)
+                return text.replace(/\s/g, "") === "" ? [] : null;
+            return pairs;
+        }
+    }
+}
+function revisionOf(dialect, path, text) {
+    if (dialect.revision !== undefined) {
+        const match = new RegExp(dialect.revision, "m").exec(text);
+        if (match !== null)
+            return match[1];
+    }
+    if (dialect.revisionFromFilename !== undefined) {
+        const match = new RegExp(dialect.revisionFromFilename).exec(basename(path));
+        if (match !== null) {
+            // The application directory disambiguates two migrations that share a
+            // numeric prefix, which is the normal case across a multi-app repository.
+            const app = /(?:^|\/)([^/]+)\/migrations\/[^/]+$/.exec(path)?.[1];
+            return app === undefined ? match[1] : `${app}/${match[1]}`;
+        }
+    }
+    return null;
+}
+/**
+ * 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
+ */
+export function readMigrations(prId, files, options = {}) {
+    const read = options.read ?? ((path) => readFileSync(path, "utf8"));
+    const resolution = options.resolution ?? 0;
+    const records = [];
+    const refusals = [];
+    let matchedDialect = 0;
+    let matchedRefusedFamily = 0;
+    let unrecognised = 0;
+    let parentsUnknown = 0;
+    for (const file of files) {
+        const refusedFamily = REFUSED.find((family) => matchesAny(file, family.files));
+        const dialect = DIALECTS.find((d) => matchesAny(file, d.files));
+        // A refused family wins over a dialect match. The dependency-list dialect's
+        // glob is broad enough to catch a timestamp-ordered directory that happens
+        // to be named `migrations/`, and admitting it there would be the invented
+        // format arriving through a glob rather than through a decision.
+        if (refusedFamily !== undefined) {
+            matchedRefusedFamily += 1;
+            refusals.push({
+                file,
+                family: refusedFamily.id,
+                reason: refusedFamily.why,
+            });
+            continue;
+        }
+        if (dialect === undefined) {
+            unrecognised += 1;
+            refusals.push({
+                file,
+                reason: "no dialect matched this path. Not a finding that the file declares no migration — " +
+                    "nothing read it.",
+            });
+            continue;
+        }
+        let text;
+        try {
+            text = read(file);
+        }
+        catch (error) {
+            unrecognised += 1;
+            refusals.push({ file, reason: `could not be read: ${String(error)}` });
+            continue;
+        }
+        const revision = revisionOf(dialect, file, text);
+        if (revision === null) {
+            matchedDialect += 1;
+            refusals.push({
+                file,
+                family: dialect.id,
+                reason: `matched the ${dialect.displayName} dialect but declares no revision id this ` +
+                    "producer could read. No record is emitted: a migration with no identity cannot " +
+                    "be a head or descend from one.",
+            });
+            continue;
+        }
+        const raw = new RegExp(dialect.parents, "m").exec(text);
+        let parents;
+        if (raw === null) {
+            parents = "unknown";
+        }
+        else {
+            const parsed = parseParents(raw[1], dialect.parentsKind);
+            parents = parsed === null ? "unknown" : parsed;
+        }
+        // A second declaration channel, where the dialect has one. Merged rather
+        // than replacing: both are real predecessors.
+        if (dialect.alsoParents !== undefined && parents !== "unknown") {
+            const extraRaw = new RegExp(dialect.alsoParents, "m").exec(text);
+            if (extraRaw !== null) {
+                const extra = parseParents(extraRaw[1], dialect.parentsKind);
+                if (extra === null)
+                    parents = "unknown";
+                else if (extra.length > 0)
+                    parents = [...new Set([...parents, ...extra])];
+            }
+        }
+        if (parents === "unknown")
+            parentsUnknown += 1;
+        matchedDialect += 1;
+        records.push({ prId, revision, parents, file, resolution });
+    }
+    return {
+        records,
+        refusals,
+        analysed: matchedDialect > 0,
+        checked: {
+            files: files.length,
+            matchedDialect,
+            matchedRefusedFamily,
+            unrecognised,
+            parentsUnknown,
+        },
+    };
+}
+//# sourceMappingURL=read.js.map

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

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

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

@@ -0,0 +1,3 @@
+export { resolveWorkspace } from "./workspace.ts";
+export type { WorkspaceDeclaration, WorkspacePairing, DeclarationSource, PackagesSource } from "./workspace.ts";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sources/workspace/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,YAAY,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/sources/workspace/index.js

@@ -0,0 +1,2 @@
+export { resolveWorkspace } from "./workspace.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/sources/workspace/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/sources/workspace/workspace.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The workspace declaration — DEC-075 §7.
+ *
+ * A multi-repo or monorepo run needs two facts a graph cannot supply on its
+ * own: which package roots exist, and which of them are meant to talk to
+ * each other. `descry.json` at the repository root is where both are
+ * declared, with an optional `descry` key inside `package.json` or
+ * `pyproject.toml` for a project that would rather not add a file. The root
+ * file wins where more than one location is present — it is the one
+ * location that works for a locally installed tool with no hosted backend,
+ * and it is greppable.
+ *
+ * ## Nx, Turborepo, pnpm and npm workspaces are read for the package LIST,
+ * ## and never for a pairing
+ *
+ * Enumerating packages from a workspace manifest is reading a declaration —
+ * the manifest states which directories are packages, so there is nothing to
+ * infer. Deciding that `apps/web` talks to `apps/api` is a name inference,
+ * and the correct mechanism already exists one layer up: a pairing is either
+ * declared here, in `descry.json`, or it falls out of a real
+ * `USES_API`/`SERVES_API` join at R3. This module supplies the declared half
+ * only; it does not guess a pairing from two directory names that sound
+ * related, for the same reason a Python `Company` must not join a
+ * TypeScript `Company` on a shared word.
+ *
+ * ## Precision over recall in the glob reader
+ *
+ * `workspaces` in `package.json` and `packages:` in `pnpm-workspace.yaml`
+ * hold globs, not paths. Only the one shape actually used across real
+ * monorepos in this project's own reference set — `dir/*`, one segment of
+ * wildcard at the end — is expanded, by listing `dir`'s subdirectories that
+ * themselves contain a `package.json`. A more elaborate glob (`**`, a
+ * mid-path wildcard, a negation) is left unexpanded and disclosed on
+ * `unexpandedGlobs` rather than approximated — an approximated package list
+ * silently mis-scopes every check that follows it.
+ */
+export interface WorkspacePairing {
+    /** Repo-relative package path, forward slashes. */
+    readonly from: string;
+    readonly to: string;
+}
+export type DeclarationSource = "descry.json" | "package.json#descry" | "pyproject.toml#tool.descry" | "none";
+export type PackagesSource = "declared" | "package.json#workspaces" | "pnpm-workspace.yaml" | "none";
+export interface WorkspaceDeclaration {
+    readonly root: string;
+    readonly declarationSource: DeclarationSource;
+    /** Repo-relative package directories, forward slashes. */
+    readonly packages: readonly string[];
+    readonly packagesSource: PackagesSource;
+    /** Declared cross-package pairings. Never inferred from names. */
+    readonly pairings: readonly WorkspacePairing[];
+    /** A workspace glob this reader would not expand, so it is disclosed rather than guessed. */
+    readonly unexpandedGlobs: readonly string[];
+}
+/**
+ * Resolve `root`'s workspace declaration: which packages it holds and which
+ * of them are declared as talking to each other. `descry.json` wins over a
+ * `package.json#descry` key, which wins over `pyproject.toml`'s
+ * `[tool.descry]` table; the first one found is used whole, never merged
+ * across locations — a package list assembled from two files is a package
+ * list nobody wrote down.
+ */
+export declare function resolveWorkspace(root: string): WorkspaceDeclaration;
+//# sourceMappingURL=workspace.d.ts.map

package/dist/sources/workspace/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../../src/sources/workspace/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAKH,MAAM,WAAW,gBAAgB;IAC/B,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,qBAAqB,GAAG,4BAA4B,GAAG,MAAM,CAAC;AAC9G,MAAM,MAAM,cAAc,GACtB,UAAU,GACV,yBAAyB,GACzB,qBAAqB,GACrB,MAAM,CAAC;AAEX,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,CAAC;IAC9C,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC/C,6FAA6F;IAC7F,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C;AA2MD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,CAuCnE"}