@proteinjs/reflection-build 2.0.2 → 2.1.0

package/test/examples/source-repository/a/node_modules/@proteinjs/util-node/dist/src/WorkspaceDeclaration.d.ts

@@ -0,0 +1,91 @@
+/** A declared-workspace rule was broken. The message names every path involved. */
+export declare class WorkspaceDeclarationError extends Error {
+    constructor(message: string);
+}
+export type DiscoveredPackage = {
+    /** Absolute package.json path — the package's identity. */
+    filePath: string;
+    packageJson: any;
+    /** `declared`: named by a workspace declaration; `crawled`: found by the bounded walk of an undeclared tree. */
+    origin: 'declared' | 'crawled';
+    /** The declaration file (lerna.json or the root package.json) that named a `declared` package. */
+    declaredBy?: string;
+};
+type Declaration = {
+    rootDir: string;
+    /** Each pattern with the file that declared it, in declaration order. */
+    patterns: Array<{
+        pattern: string;
+        source: string;
+    }>;
+};
+/**
+ * The ONE owner of workspace membership: which package.json files belong to the workspace rooted
+ * at a directory.
+ *
+ * Membership is DECLARED, never crawled. A directory holding a `lerna.json` (its `packages`
+ * globs; lerna's own default `packages/*` when the field is absent) or a root `package.json`
+ * carrying `workspacePackages` (extra roots the workspace tooling builds alongside lerna's
+ * members — e.g. an app's `ops/*` tools that lerna must not version) is a workspace ROOT. Its
+ * members are exactly what it declares, and it OWNS its subtree: nothing undeclared beneath it is
+ * a member, however the tree is walked from above. A member that is itself a root expands through
+ * its own declaration (the metarepo's nested lerna roots).
+ *
+ * Why: the previous crawl (every package.json under the root, keyed by name, last path wins)
+ * let a CI fixture tree whose package.json files reused the app's own package names shadow the
+ * real packages — build-workspace built "1 package in workspace" and the release image shipped
+ * with no server dist (n3xah/app Deploy to Test run 33747781291, 2026-09-03). A declaration
+ * cannot be shadowed by a file nobody declared.
+ *
+ * A tree with no declaration at its root (the n3xa metarepo root) still crawls — bounded exactly
+ * as before: never into hidden directories, `node_modules`, `dist`, or through symlinks — and
+ * hands every declared root it meets to that root's declaration.
+ *
+ * Hard errors, each naming its paths: a declared literal path with no package.json; two leaf
+ * packages sharing a name (dependencies resolve to members BY NAME). Containers — a package.json
+ * with members beneath it; every root in the metarepo is named `root` — are identified by path
+ * and exempt from the name rule.
+ *
+ * npm's own `workspaces` field is deliberately NOT read: it changes how `npm i` installs at the
+ * root, which is a different install model from the per-package installs this tooling performs.
+ */
+export declare class WorkspaceDeclaration {
+    /** Root package.json field naming extra member globs beside lerna's `packages`. */
+    static readonly EXTRA_PACKAGES_FIELD = "workspacePackages";
+    private static readonly lernaDefaultPackages;
+    private static readonly prunedDirNames;
+    /** Every member package.json of the workspace rooted at `rootDir`, sorted by path. */
+    static discover(rootDir: string): Promise<DiscoveredPackage[]>;
+    /** The declaration at `dir` when `dir` is a workspace root; undefined otherwise. */
+    static read(dir: string): Promise<Declaration | undefined>;
+    /** A declared root: its own package.json (the container), then exactly its declared members. */
+    private static discoverDeclared;
+    /**
+     * The bounded walk of an UNDECLARED tree (the metarepo root): every package.json it meets is a
+     * member, and every declared root it meets is handed to that root's declaration instead of
+     * being walked. Never enters hidden directories, node_modules, or dist; never follows symlinks
+     * (`withFileTypes` reports a symlink as neither directory nor file).
+     */
+    private static crawl;
+    /**
+     * The directories a declared pattern names under `rootDir`, lerna's semantics: a literal path
+     * MUST hold a package.json (hard error otherwise — a declared package that does not exist is
+     * a broken declaration, never a silent skip); a glob (`*` within a segment, `**` for any depth)
+     * matches directories that hold one, walking with the same prune rules as the crawl. A declared
+     * root met inside a glob's walk is matched as a whole and not walked past — it owns its subtree.
+     */
+    private static expand;
+    private static matchSegments;
+    /** Leaf packages resolve by name; two leaves with one name is a broken workspace, not a tie to break. */
+    private static assertNoLeafNameCollisions;
+    private static add;
+    private static assertPattern;
+    private static segmentMatcher;
+    private static isPrunedDirName;
+    /** Real (non-symlink, non-pruned) child directories of `dir`. */
+    private static childDirs;
+    private static isRealDir;
+    private static exists;
+    private static readJsonIfExists;
+}
+export {};