@nielspeter/eess-ts 0.2.1 → 0.5.0

package/dist/core/project-relative.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Make a project-relative glob work, instead of failing loudly — plan 0067 C.
+ *
+ * Globs are matched against **absolute** file paths, so `'src/domain/**'`
+ * matches nothing. That is the single commonest real mistake with this library:
+ * it is the shape 0.18.1 was released for, and as of **0.34.0** it is a hard
+ * build failure telling the author to prefix `'**\/'`.
+ *
+ * Prefixing works but says something different. `'**\/src/domain/**'` matches a
+ * `src/domain` **anywhere** — including `vendor/thing/src/domain`, and
+ * including a second `src/` nested inside a monorepo package. What the author
+ * meant was the one at the project root. 0067 called normalization "the root
+ * cause" fix for that reason, and 0069 sequenced it directly after R3b.
+ *
+ * So an unanchored glob is matched against the path **relative to the
+ * tsconfig's directory**, in addition to the absolute path. Both spellings keep
+ * working and they mean different things:
+ *
+ * | glob                  | matches                                     |
+ * | --------------------- | ------------------------------------------- |
+ * | `'src/domain/**'`     | that folder **at the project root**         |
+ * | `'**\/src/domain/**'` | a `src/domain` **anywhere** in the project  |
+ * | `'/abs/src/domain/**'`| exactly that absolute path                  |
+ *
+ * ## Why the root comes from the element, not from the builder
+ *
+ * A predicate is constructed two ways that must not diverge:
+ * `.that().resideInFolder(g)`, where the builder knows the project, and
+ * `.that().satisfy(resideInFolder(g))`, where nothing does.
+ * `tests/core/glob-declaration.test.ts` exists to assert the two spellings
+ * agree, and threading the root through only the first would break that.
+ *
+ * Every `Located` element can reach its own `SourceFile`, and ts-morph carries
+ * the tsconfig it was loaded from on the project's compiler options. So the
+ * root is derived where the match happens, from the element itself, and both
+ * spellings get it for free.
+ *
+ * `configFilePath` is `undefined` for a project built in memory or without a
+ * tsconfig. That is a genuine "no root known" and normalization is skipped —
+ * the glob keeps its absolute-only meaning rather than being matched against
+ * something invented.
+ */
+import type { Project as TsMorphProject, SourceFile } from 'ts-morph';
+/**
+ * Whether a glob can already match an absolute path, so the `**\/` hint would
+ * be a no-op (or worse). Covers POSIX-absolute and Windows drive-absolute
+ * globs as well as an explicit globstar.
+ *
+ * Lives here rather than in `glob-diagnosis.ts` (which re-exports it) because
+ * `isProjectRelative` below is defined as its negation, and this module sits
+ * under the one that diagnoses.
+ */
+export declare function isAnchored(glob: string): boolean;
+/**
+ * Does this glob name a location relative to the project root?
+ *
+ * Only an **unanchored, relative** glob is normalized. `'**\/x'` is explicitly
+ * "anywhere" and must keep meaning that; `'/abs/x'` is already absolute. So
+ * this is the same population `syntacticFault` calls `unanchored`, which is
+ * what makes the two consistent: a glob stops being reported dead for being
+ * unanchored exactly when it starts working.
+ */
+export declare function isProjectRelative(glob: string): boolean;
+/**
+ * Record the directories a project was loaded from.
+ *
+ * Load-bearing for `workspace()`, which has several. For a single-tsconfig
+ * `project()` it is **defence in depth and not independently observable**:
+ * removing that call leaves every test green, because `rootOf` then falls
+ * through to ts-morph's `configFilePath`, which agrees. Recorded rather than
+ * papered over — a sabotage row that survives because the behaviour is
+ * genuinely redundant is a different thing from a missing guard, and the next
+ * person to see it green should not go hunting for a test to write.
+ */
+export declare function registerProjectRoots(tsMorphProject: TsMorphProject, tsConfigPaths: readonly string[]): void;
+/**
+ * The project root implied by a tsconfig path.
+ *
+ * Preferred wherever the caller holds the `ArchProject`, because it is the path
+ * the user named rather than what ts-morph recorded — `getCompilerOptions()
+ * .configFilePath` is `undefined` for an in-memory project even when the
+ * `ArchProject` carries a perfectly good path, and normalization then silently
+ * did not happen. The predicates cannot use this (they see only an element, by
+ * design, so the builder and `.satisfy()` spellings cannot diverge); the slice
+ * resolver can.
+ */
+export declare function rootFromTsConfigPath(tsConfigPath: string): string | undefined;
+export declare function rootOf(sourceFile: SourceFile, fallbackTsConfigPath?: string): string | undefined;
+/**
+ * `absolutePath` relative to the project root, or `undefined` when it sits
+ * outside the root or the root is unknown.
+ *
+ * Never `path.relative`, which emits `../../..` for a path above the root and
+ * so encodes the root's depth — machine-dependent, and the mistake
+ * `path-universe.ts` documents avoiding for the same reason.
+ */
+export declare function relativeToRoot(sourceFile: SourceFile, absolutePath: string, fallbackTsConfigPath?: string): string | undefined;
+//# sourceMappingURL=project-relative.d.ts.map

package/dist/core/project-relative.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-relative.d.ts","sourceRoot":"","sources":["../../src/core/project-relative.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,OAAO,KAAK,EAAE,OAAO,IAAI,cAAc,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAErE;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAgCvD;AA+BD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,cAAc,EAAE,cAAc,EAC9B,aAAa,EAAE,SAAS,MAAM,EAAE,GAC/B,IAAI,CAKN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAY7E;AAOD,wBAAgB,MAAM,CAAC,UAAU,EAAE,UAAU,EAAE,oBAAoB,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAqChG;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,UAAU,EACtB,YAAY,EAAE,MAAM,EACpB,oBAAoB,CAAC,EAAE,MAAM,GAC5B,MAAM,GAAG,SAAS,CAKpB"}

package/dist/core/project-relative.js

@@ -0,0 +1,185 @@
+/**
+ * Whether a glob can already match an absolute path, so the `**\/` hint would
+ * be a no-op (or worse). Covers POSIX-absolute and Windows drive-absolute
+ * globs as well as an explicit globstar.
+ *
+ * Lives here rather than in `glob-diagnosis.ts` (which re-exports it) because
+ * `isProjectRelative` below is defined as its negation, and this module sits
+ * under the one that diagnoses.
+ */
+export function isAnchored(glob) {
+    return glob.startsWith('**/') || glob.startsWith('/') || /^[A-Za-z]:\//.test(glob);
+}
+/**
+ * Does this glob name a location relative to the project root?
+ *
+ * Only an **unanchored, relative** glob is normalized. `'**\/x'` is explicitly
+ * "anywhere" and must keep meaning that; `'/abs/x'` is already absolute. So
+ * this is the same population `syntacticFault` calls `unanchored`, which is
+ * what makes the two consistent: a glob stops being reported dead for being
+ * unanchored exactly when it starts working.
+ */
+export function isProjectRelative(glob) {
+    // A `./` segment is excluded, and that exclusion is load-bearing rather than
+    // fussy. `syntacticFault` reports `dot-segment` for a `./` anywhere in a
+    // glob, so normalizing one would make the rule MATCH at runtime while the
+    // gate still reported it dead — two derivations disagreeing about the same
+    // glob, which is the failure this project spends most of its guards on.
+    // Measured before this line existed: `'./src/domain/**'` selected 3 subjects
+    // and produced a dead-selector finding in the same run.
+    //
+    // `./` is a mistake in both worlds — it never occurs in an absolute path and
+    // it says nothing extra in a relative one — so the honest fix is to leave it
+    // failing, with advice that says to remove it.
+    // `..` is not relative-to-the-root in any usable sense: containment returns
+    // `undefined` for anything above the root, deliberately, so a `../`
+    // glob would normalize to nothing and be reported dead with three false
+    // causes. Excluded alongside `./` — both are mistakes in both readings.
+    if (/(?:^|\/)\.\.?\//.test(glob))
+        return false;
+    // Derived from `isAnchored`, not restated. They were two lists and disagreed:
+    // `isAnchored` recognises a drive-absolute `C:/x/**` and this did not, so a
+    // Windows path was declared project-relative. Benign today — it still matches
+    // the absolute path — but `base` is a function of this at three sites now,
+    // and `base` affects the verdict.
+    // `isAnchored` covers `/x`, `**/x` and a drive-absolute `C:/x` — the last of
+    // which this used to miss, declaring a Windows path project-relative.
+    if (isAnchored(glob))
+        return false;
+    // `*/x/**` is deliberately NOT normalized, even though it is unanchored.
+    // Normalizing it would make it match, which sounds like an improvement until
+    // you notice it is the LAST reachable `unanchored` fault for a path glob —
+    // the anchor advice, and the whole `ANCHOR_ADVICE` grouping in the slice
+    // discovery message, would become unreachable code. Left failing, with a
+    // remedy that works: `'**/x/**'`.
+    return !glob.startsWith('*/');
+}
+/**
+ * The directory holding the tsconfig this element's project was loaded from.
+ *
+ * Forward slashes, no trailing separator — the same normalization
+ * `path-universe.ts` applies, so the two cannot disagree about what the root
+ * is. `undefined` when the project has no tsconfig.
+ */
+/**
+ * Every directory a project was loaded from, by ts-morph `Project`.
+ *
+ * A **workspace has no single root.** `workspace([a, b])` sets
+ * `ArchProject.tsConfigPath` to the alphabetically first config, so resolving
+ * "the project root" from it silently meant *that one package*: measured on a
+ * two-package workspace, `'src/api/**'` matched `packages/alpha` and not
+ * `packages/beta`, and adding a package named `aaa` would have changed which
+ * one it meant. That is the machine-dependent shape bug 0011 already cost this
+ * project once — a rule scoped by a name nobody chose deliberately.
+ *
+ * So a file resolves against **the root that contains it**, and every root is
+ * kept. For a single-tsconfig project there is one, and the behaviour is
+ * exactly what it was.
+ *
+ * A `WeakMap` on the ts-morph project, because a predicate sees only an
+ * element: `sourceFile.getProject()` is the one handle both the predicate and
+ * the slice resolver can reach, and ts-morph itself records only the primary
+ * config.
+ */
+const rootsByProject = new WeakMap();
+/**
+ * Record the directories a project was loaded from.
+ *
+ * Load-bearing for `workspace()`, which has several. For a single-tsconfig
+ * `project()` it is **defence in depth and not independently observable**:
+ * removing that call leaves every test green, because `rootOf` then falls
+ * through to ts-morph's `configFilePath`, which agrees. Recorded rather than
+ * papered over — a sabotage row that survives because the behaviour is
+ * genuinely redundant is a different thing from a missing guard, and the next
+ * person to see it green should not go hunting for a test to write.
+ */
+export function registerProjectRoots(tsMorphProject, tsConfigPaths) {
+    const roots = tsConfigPaths
+        .map((configPath) => rootFromTsConfigPath(configPath))
+        .filter((root) => root !== undefined);
+    if (roots.length > 0)
+        rootsByProject.set(tsMorphProject, roots);
+}
+/**
+ * The project root implied by a tsconfig path.
+ *
+ * Preferred wherever the caller holds the `ArchProject`, because it is the path
+ * the user named rather than what ts-morph recorded — `getCompilerOptions()
+ * .configFilePath` is `undefined` for an in-memory project even when the
+ * `ArchProject` carries a perfectly good path, and normalization then silently
+ * did not happen. The predicates cannot use this (they see only an element, by
+ * design, so the builder and `.satisfy()` spellings cannot diverge); the slice
+ * resolver can.
+ */
+export function rootFromTsConfigPath(tsConfigPath) {
+    if (tsConfigPath === '')
+        return undefined;
+    const normalized = tsConfigPath.replaceAll('\\', '/');
+    const lastSlash = normalized.lastIndexOf('/');
+    if (lastSlash === -1)
+        return undefined;
+    // A tsconfig AT the filesystem root gives `'/'`, not `''`. Returning `''`
+    // overloaded one value with two meanings — "no root known" and "the root is
+    // `/`" — and the three copies of this derivation disagreed about which:
+    // measured on `/tsconfig.json`, the rule discovered its file and `diagnose()`
+    // called the same glob dead, in one run. Reachable in a container that mounts
+    // the repository at `/`.
+    return lastSlash === 0 ? '/' : normalized.slice(0, lastSlash);
+}
+/** The prefix a path under `root` starts with. `'/'` is its own prefix. */
+function prefixOf(root) {
+    return root === '/' ? '/' : `${root}/`;
+}
+export function rootOf(sourceFile, fallbackTsConfigPath) {
+    const filePath = sourceFile.getFilePath().replaceAll('\\', '/');
+    // The registered root that CONTAINS this file, longest first — a nested
+    // package's tsconfig must win over the repository's, or every file in it
+    // resolves against the outer root and the inner one never applies.
+    const registered = rootsByProject.get(sourceFile.getProject());
+    if (registered !== undefined) {
+        // Roots WERE registered for this project (a real `workspace()`) — fail
+        // CLOSED here (ADR-009) rather than falling through to the generic fallback
+        // below. That fallback resolves to the tie-break-winner's own tsconfig for a
+        // `workspace()`-built project, which is a specific, plausible-looking, WRONG
+        // answer for a file outside every registered package (a shared root-level
+        // `.d.ts`, a broad `include`/`references` reaching outside a package's own
+        // directory) — exactly the silent mis-scoping this module exists to
+        // eliminate, just relocated to the edges. `fallbackTsConfigPath` doesn't
+        // rescue it either: for a `workspace()` caller it is typically the primary
+        // config's own path (see `resolveByDefinition`'s `project.tsConfigPath`), so
+        // honoring it here would reintroduce the same bug through the back door.
+        //
+        // eess's own fix (plan 0148 Phase 1). The wholesale engine copy of plan 0165
+        // reverted it to `if (best !== undefined) return best`, which reads as a
+        // harmless guard and is in fact the fall-through. Pinned by
+        // `tests/core/project-relative.test.ts` · `a file outside every registered
+        // root of a real workspace() is unresolved, not silently the tie-break
+        // winner`.
+        const containing = registered
+            .filter((root) => filePath.startsWith(prefixOf(root)))
+            .sort((a, b) => b.length - a.length);
+        return containing[0];
+    }
+    // A project built without going through `project()`/`workspace()` — a test
+    // double, or an in-memory project, where ts-morph records no config path.
+    if (fallbackTsConfigPath !== undefined)
+        return rootFromTsConfigPath(fallbackTsConfigPath);
+    const configFilePath = sourceFile.getProject().getCompilerOptions().configFilePath;
+    return typeof configFilePath === 'string' ? rootFromTsConfigPath(configFilePath) : undefined;
+}
+/**
+ * `absolutePath` relative to the project root, or `undefined` when it sits
+ * outside the root or the root is unknown.
+ *
+ * Never `path.relative`, which emits `../../..` for a path above the root and
+ * so encodes the root's depth — machine-dependent, and the mistake
+ * `path-universe.ts` documents avoiding for the same reason.
+ */
+export function relativeToRoot(sourceFile, absolutePath, fallbackTsConfigPath) {
+    const root = rootOf(sourceFile, fallbackTsConfigPath);
+    if (root === undefined)
+        return undefined;
+    const prefix = prefixOf(root);
+    return absolutePath.startsWith(prefix) ? absolutePath.slice(prefix.length) : undefined;
+}
+//# sourceMappingURL=project-relative.js.map

package/dist/core/project-relative.js.map

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

package/dist/core/project.d.ts

@@ -1,4 +1,4 @@
-import { Project, type SourceFile } from 'ts-morph';
+import { Project, type SourceFile, type CompilerOptions } from 'ts-morph';
 /**
  * A loaded TypeScript project. Returned by `project()`.
  *
@@ -10,6 +10,12 @@ export interface ArchProject {
     readonly tsConfigPath: string;
     /** Returns all source files included by the tsconfig. */
     getSourceFiles(): SourceFile[];
+    /**
+     * Resolved TypeScript compiler options (after `extends`), as `tsc` computes
+     * them. Optional so bare `ArchProject` literals (test doubles) stay valid;
+     * `project()` and `workspace()` always implement it. Used by `tsconfig()`.
+     */
+    getCompilerOptions?(): CompilerOptions;
     /**
      * The underlying ts-morph Project.
      * @internal Used by entry points — not part of the public API.

package/dist/core/project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../src/core/project.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,UAAU,CAAA;AAInD;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAE7B,yDAAyD;IACzD,cAAc,IAAI,UAAU,EAAE,CAAA;IAE9B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B;AAID;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,WAAW,CA6BzD;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,WAAW,CAuD9D;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAGxC"}
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../src/core/project.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,UAAU,CAAA;AAOzE;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAE7B,yDAAyD;IACzD,cAAc,IAAI,UAAU,EAAE,CAAA;IAE9B;;;;OAIG;IACH,kBAAkB,CAAC,IAAI,eAAe,CAAA;IAEtC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B;AAID;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,WAAW,CAmCzD;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,WAAW,CAuE9D;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAQxC"}

package/dist/core/project.js

@@ -1,6 +1,10 @@
+import { ArchConfigError } from '@nielspeter/eess';
 import { Project } from 'ts-morph';
 import path from 'node:path';
+import { clearRegisteredCaches } from '@nielspeter/eess/internal';
 import fs from 'node:fs';
+import { registerProjectRoots } from './project-relative.js';
+import { registerRootCompilerOptions } from './per-root-compiler-options.js';
 const cache = new Map();
 /**
  * Load a TypeScript project from a tsconfig.json path.
@@ -19,18 +23,22 @@ export function project(tsConfigPath) {
         return cached;
     }
     if (!fs.existsSync(resolved)) {
-        throw new Error(`tsconfig not found: ${resolved}\n` +
+        throw new ArchConfigError('project', `tsconfig not found: ${resolved}\n` +
             `Provide a valid path to tsconfig.json, e.g. project('tsconfig.json') or project('./packages/app/tsconfig.json')`);
     }
     const tsMorphProject = new Project({
         tsConfigFilePath: resolved,
     });
+    registerProjectRoots(tsMorphProject, [resolved]);
     const archProject = {
         tsConfigPath: resolved,
         _project: tsMorphProject,
         getSourceFiles() {
             return tsMorphProject.getSourceFiles();
         },
+        getCompilerOptions() {
+            return tsMorphProject.getCompilerOptions();
+        },
     };
     cache.set(resolved, archProject);
     return archProject;
@@ -67,7 +75,7 @@ const workspaceCache = new Map();
  */
 export function workspace(tsConfigPaths) {
     if (tsConfigPaths.length === 0) {
-        throw new Error('workspace() requires at least one tsconfig path.\n' +
+        throw new ArchConfigError('workspace', 'workspace() requires at least one tsconfig path.\n' +
             'Example: workspace(["apps/web/tsconfig.json", "packages/shared/tsconfig.json"])');
     }
     // Sort resolved paths so the primary config (first) is deterministic
@@ -85,14 +93,14 @@ export function workspace(tsConfigPaths) {
     // Validate all paths exist before creating the project
     for (const resolved of resolvedPaths) {
         if (!fs.existsSync(resolved)) {
-            throw new Error(`tsconfig not found: ${resolved}\n` +
+            throw new ArchConfigError('workspace', `tsconfig not found: ${resolved}\n` +
                 `Provide valid paths to tsconfig.json files in the workspace() call.`);
         }
     }
     // Create project with the alphabetically first tsconfig's compiler options
     const primaryConfig = resolvedPaths[0];
     if (!primaryConfig)
-        throw new Error('No resolved paths available');
+        throw new ArchConfigError('workspace', 'No resolved paths available');
     const tsMorphProject = new Project({
         tsConfigFilePath: primaryConfig,
     });
@@ -102,12 +110,24 @@ export function workspace(tsConfigPaths) {
         if (configPath)
             tsMorphProject.addSourceFilesFromTsConfig(configPath);
     }
+    // EVERY config, not just the primary: a relative glob resolves against the
+    // package that contains the file, so `'src/api/**'` means each package's
+    // `src/api` rather than the alphabetically-first one's (bug 0035).
+    registerProjectRoots(tsMorphProject, resolvedPaths);
+    // Same argument, one field over: compiler options are per package too, and
+    // `addSourceFilesFromTsConfig` above adds files WITHOUT adding options — so
+    // `getCompilerOptions()` answers for the primary config whatever package a file is in.
+    // Bug 0058, measured wrong in both directions before this line existed.
+    registerRootCompilerOptions(tsMorphProject, resolvedPaths);
     const archProject = {
         tsConfigPath: primaryConfig,
         _project: tsMorphProject,
         getSourceFiles() {
             return tsMorphProject.getSourceFiles();
         },
+        getCompilerOptions() {
+            return tsMorphProject.getCompilerOptions();
+        },
     };
     workspaceCache.set(cacheKey, archProject);
     return archProject;
@@ -123,5 +143,10 @@ export function workspace(tsConfigPaths) {
 export function resetProjectCache() {
     cache.clear();
     workspaceCache.clear();
+    // Plan 0075/0076: the memoized element collections and module edges are keyed
+    // on objects this function replaces, so `project()` callers are covered by
+    // identity alone. A consumer holding their OWN `ArchProject` is not, and this
+    // is their documented way to invalidate after mutating the ts-morph project.
+    clearRegisteredCaches();
 }
 //# sourceMappingURL=project.js.map

package/dist/core/project.js.map

@@ -1 +1 @@
-{"version":3,"file":"project.js","sourceRoot":"","sources":["../../src/core/project.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../../src/core/project.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,EAAE,OAAO,EAAyC,MAAM,UAAU,CAAA;AACzE,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AACjE,OAAO,EAAE,MAAM,SAAS,CAAA;AACxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,EAAE,2BAA2B,EAAE,MAAM,gCAAgC,CAAA;AA6B5E,MAAM,KAAK,GAAG,IAAI,GAAG,EAAuB,CAAA;AAE5C;;;;;;;;;GASG;AACH,MAAM,UAAU,OAAO,CAAC,YAAoB;IAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,CAAA;IAE3C,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;IAClC,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,MAAM,CAAA;IACf,CAAC;IAED,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,eAAe,CACvB,SAAS,EACT,uBAAuB,QAAQ,IAAI;YACjC,iHAAiH,CACpH,CAAA;IACH,CAAC;IAED,MAAM,cAAc,GAAG,IAAI,OAAO,CAAC;QACjC,gBAAgB,EAAE,QAAQ;KAC3B,CAAC,CAAA;IAEF,oBAAoB,CAAC,cAAc,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAA;IAEhD,MAAM,WAAW,GAAgB;QAC/B,YAAY,EAAE,QAAQ;QACtB,QAAQ,EAAE,cAAc;QACxB,cAAc;YACZ,OAAO,cAAc,CAAC,cAAc,EAAE,CAAA;QACxC,CAAC;QACD,kBAAkB;YAChB,OAAO,cAAc,CAAC,kBAAkB,EAAE,CAAA;QAC5C,CAAC;KACF,CAAA;IAED,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAA;IAChC,OAAO,WAAW,CAAA;AACpB,CAAC;AAED,mEAAmE;AAEnE,MAAM,cAAc,GAAG,IAAI,GAAG,EAAuB,CAAA;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,SAAS,CAAC,aAAuB;IAC/C,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,eAAe,CACvB,WAAW,EACX,oDAAoD;YAClD,iFAAiF,CACpF,CAAA;IACH,CAAC;IAED,qEAAqE;IACrE,0EAA0E;IAC1E,iFAAiF;IACjF,mFAAmF;IACnF,MAAM,aAAa,GAAG,aAAa;SAChC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;SAC3B,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAE/C,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACzC,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;IAC3C,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,MAAM,CAAA;IACf,CAAC;IAED,uDAAuD;IACvD,KAAK,MAAM,QAAQ,IAAI,aAAa,EAAE,CAAC;QACrC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,eAAe,CACvB,WAAW,EACX,uBAAuB,QAAQ,IAAI;gBACjC,qEAAqE,CACxE,CAAA;QACH,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,MAAM,aAAa,GAAG,aAAa,CAAC,CAAC,CAAC,CAAA;IACtC,IAAI,CAAC,aAAa;QAAE,MAAM,IAAI,eAAe,CAAC,WAAW,EAAE,6BAA6B,CAAC,CAAA;IACzF,MAAM,cAAc,GAAG,IAAI,OAAO,CAAC;QACjC,gBAAgB,EAAE,aAAa;KAChC,CAAC,CAAA;IAEF,4CAA4C;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9C,MAAM,UAAU,GAAG,aAAa,CAAC,CAAC,CAAC,CAAA;QACnC,IAAI,UAAU;YAAE,cAAc,CAAC,0BAA0B,CAAC,UAAU,CAAC,CAAA;IACvE,CAAC;IAED,2EAA2E;IAC3E,yEAAyE;IACzE,mEAAmE;IACnE,oBAAoB,CAAC,cAAc,EAAE,aAAa,CAAC,CAAA;IAEnD,2EAA2E;IAC3E,4EAA4E;IAC5E,uFAAuF;IACvF,wEAAwE;IACxE,2BAA2B,CAAC,cAAc,EAAE,aAAa,CAAC,CAAA;IAE1D,MAAM,WAAW,GAAgB;QAC/B,YAAY,EAAE,aAAa;QAC3B,QAAQ,EAAE,cAAc;QACxB,cAAc;YACZ,OAAO,cAAc,CAAC,cAAc,EAAE,CAAA;QACxC,CAAC;QACD,kBAAkB;YAChB,OAAO,cAAc,CAAC,kBAAkB,EAAE,CAAA;QAC5C,CAAC;KACF,CAAA;IAED,cAAc,CAAC,GAAG,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAA;IACzC,OAAO,WAAW,CAAA;AACpB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB;IAC/B,KAAK,CAAC,KAAK,EAAE,CAAA;IACb,cAAc,CAAC,KAAK,EAAE,CAAA;IACtB,8EAA8E;IAC9E,2EAA2E;IAC3E,8EAA8E;IAC9E,6EAA6E;IAC7E,qBAAqB,EAAE,CAAA;AACzB,CAAC"}