@mxpicture/build-api 0.2.55 → 0.2.57

package/dist/vscode/vscode.profiles.d.ts

@@ -1,6 +1,43 @@
 import { VSCodeProfile } from "../types/types.vscode.js";
+/**
+ * Returns all VS Code user-data profiles.
+ *
+ * @remarks
+ * Each profile is resolved from the persisted {@link storage} and enriched
+ * with the absolute path to its `settings.json` via {@link profileSettingsPath}.
+ *
+ * @returns An array of {@link VSCodeProfile} objects for every configured profile.
+ */
 export declare const profiles: () => VSCodeProfile[];
+/**
+ * Resolves the active VS Code profile for a given workspace directory.
+ *
+ * @remarks
+ * The workspace root is located via {@link findWorkspaceRoot}, then matched
+ * against the profile-to-workspace associations stored in VS Code's
+ * `storage.json`. Throws if no matching profile is found.
+ *
+ * @param dir - The directory to resolve the workspace from. Defaults to the
+ *   current working directory.
+ * @returns A promise that resolves to the active {@link VSCodeProfile}.
+ * @throws If no active profile is associated with the resolved workspace.
+ */
 export declare const activeProfile: (dir?: string) => Promise<VSCodeProfile>;
+/**
+ * Builds the absolute path to a profile's `settings.json` file.
+ *
+ * @param profile - The unique location identifier of the profile.
+ * @returns The absolute path to `settings.json` inside the profile's directory.
+ */
 export declare const profileSettingsPath: (profile: string) => string;
+/**
+ * Returns the absolute path to the default (global) `settings.json` file.
+ *
+ * @remarks
+ * This is the settings file used when no named profile is active.
+ *
+ * @returns The absolute path to the default `settings.json` in the VS Code
+ *   `User` directory.
+ */
 export declare const defaultSettingsPath: () => string;
 //# sourceMappingURL=vscode.profiles.d.ts.map

package/dist/vscode/vscode.profiles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vscode.profiles.d.ts","sourceRoot":"","sources":["../../src/vscode/vscode.profiles.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAMzD,eAAO,MAAM,QAAQ,QAAO,aAAa,EAOtC,CAAC;AAEJ,eAAO,MAAM,aAAa,GAAU,MAAM,MAAM,KAAG,OAAO,CAAC,aAAa,CAkBvE,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAAI,SAAS,MAAM,KAAG,MACQ,CAAC;AAE/D,eAAO,MAAM,mBAAmB,QAAO,MACE,CAAC"}
+{"version":3,"file":"vscode.profiles.d.ts","sourceRoot":"","sources":["../../src/vscode/vscode.profiles.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAMzD;;;;;;;;GAQG;AACH,eAAO,MAAM,QAAQ,QAAO,aAAa,EAOtC,CAAC;AAEJ;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,GAAU,MAAM,MAAM,KAAG,OAAO,CAAC,aAAa,CAkBvE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS,MAAM,KAAG,MACQ,CAAC;AAE/D;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,QAAO,MACE,CAAC"}

package/dist/vscode/vscode.profiles.js

@@ -3,11 +3,33 @@ import { storage } from "./vscode.storage.js";
 import { configUserPath } from "./vscode.config.js";
 import { findWorkspaceRoot } from "../workspace/workspace.common.js";
 import { cwd } from "node:process";
+/**
+ * Returns all VS Code user-data profiles.
+ *
+ * @remarks
+ * Each profile is resolved from the persisted {@link storage} and enriched
+ * with the absolute path to its `settings.json` via {@link profileSettingsPath}.
+ *
+ * @returns An array of {@link VSCodeProfile} objects for every configured profile.
+ */
 export const profiles = () => storage().userDataProfiles.map((prof) => ({
     name: prof.name,
     location: prof.location,
     settingsPath: profileSettingsPath(prof.location),
 }));
+/**
+ * Resolves the active VS Code profile for a given workspace directory.
+ *
+ * @remarks
+ * The workspace root is located via {@link findWorkspaceRoot}, then matched
+ * against the profile-to-workspace associations stored in VS Code's
+ * `storage.json`. Throws if no matching profile is found.
+ *
+ * @param dir - The directory to resolve the workspace from. Defaults to the
+ *   current working directory.
+ * @returns A promise that resolves to the active {@link VSCodeProfile}.
+ * @throws If no active profile is associated with the resolved workspace.
+ */
 export const activeProfile = async (dir) => {
     const foundWS = await findWorkspaceRoot(dir ?? cwd());
     const storageContent = storage();
@@ -26,6 +48,21 @@ export const activeProfile = async (dir) => {
         throw new Error("No active profile found");
     return foundProfile;
 };
+/**
+ * Builds the absolute path to a profile's `settings.json` file.
+ *
+ * @param profile - The unique location identifier of the profile.
+ * @returns The absolute path to `settings.json` inside the profile's directory.
+ */
 export const profileSettingsPath = (profile) => join(configUserPath(), "profiles", profile, "settings.json");
+/**
+ * Returns the absolute path to the default (global) `settings.json` file.
+ *
+ * @remarks
+ * This is the settings file used when no named profile is active.
+ *
+ * @returns The absolute path to the default `settings.json` in the VS Code
+ *   `User` directory.
+ */
 export const defaultSettingsPath = () => join(configUserPath(), "settings.json");
 //# sourceMappingURL=vscode.profiles.js.map

package/dist/vscode/vscode.profiles.js.map

@@ -1 +1 @@
-{"version":3,"file":"vscode.profiles.js","sourceRoot":"","sources":["../../src/vscode/vscode.profiles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAEnC,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAoB,EAAE,CAC5C,OAAO,EAAE,CAAC,gBAAgB,CAAC,GAAG,CAC5B,CAAC,IAAI,EAAiB,EAAE,CAAC,CAAC;IACxB,IAAI,EAAE,IAAI,CAAC,IAAI;IACf,QAAQ,EAAE,IAAI,CAAC,QAAQ;IACvB,YAAY,EAAE,mBAAmB,CAAC,IAAI,CAAC,QAAQ,CAAC;CACjD,CAAC,CACH,CAAC;AAEJ,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,EAAE,GAAY,EAA0B,EAAE;IAC1E,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,GAAG,IAAI,GAAG,EAAE,CAAC,CAAC;IACtD,MAAM,cAAc,GAAG,OAAO,EAAE,CAAC;IACjC,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;IACzB,IAAI,YAAuC,CAAC;IAE5C,wCAAwC;IACxC,KAAK,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CACxC,cAAc,CAAC,mBAAmB,CAAC,UAAU,CAC9C,EAAE,CAAC;QACF,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QACnC,IAAI,OAAO,CAAC,QAAQ,KAAK,IAAI;YAAE,SAAS;QACxC,YAAY,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC;QAC/D,IAAI,YAAY;YAAE,MAAM;IAC1B,CAAC;IAED,IAAI,CAAC,YAAY;QAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC9D,OAAO,YAAY,CAAC;AACtB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,OAAe,EAAU,EAAE,CAC7D,IAAI,CAAC,cAAc,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE,eAAe,CAAC,CAAC;AAE/D,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAW,EAAE,CAC9C,IAAI,CAAC,cAAc,EAAE,EAAE,eAAe,CAAC,CAAC","sourcesContent":["import { join } from \"node:path\";\nimport { VSCodeProfile } from \"../types/types.vscode.js\";\nimport { storage } from \"./vscode.storage.js\";\nimport { configUserPath } from \"./vscode.config.js\";\nimport { findWorkspaceRoot } from \"../workspace/workspace.common.js\";\nimport { cwd } from \"node:process\";\n\nexport const profiles = (): VSCodeProfile[] =>\n  storage().userDataProfiles.map(\n    (prof): VSCodeProfile => ({\n      name: prof.name,\n      location: prof.location,\n      settingsPath: profileSettingsPath(prof.location),\n    }),\n  );\n\nexport const activeProfile = async (dir?: string): Promise<VSCodeProfile> => {\n  const foundWS = await findWorkspaceRoot(dir ?? cwd());\n  const storageContent = storage();\n  const profs = profiles();\n  let foundProfile: VSCodeProfile | undefined;\n\n  // eslint-disable-next-line prefer-const\n  for (let [path, profile] of Object.entries(\n    storageContent.profileAssociations.workspaces,\n  )) {\n    path = path.replace(\"file://\", \"\");\n    if (foundWS.filePath !== path) continue;\n    foundProfile = profs.find((prof) => prof.location === profile);\n    if (foundProfile) break;\n  }\n\n  if (!foundProfile) throw new Error(\"No active profile found\");\n  return foundProfile;\n};\n\nexport const profileSettingsPath = (profile: string): string =>\n  join(configUserPath(), \"profiles\", profile, \"settings.json\");\n\nexport const defaultSettingsPath = (): string =>\n  join(configUserPath(), \"settings.json\");\n"]}
+{"version":3,"file":"vscode.profiles.js","sourceRoot":"","sources":["../../src/vscode/vscode.profiles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAEnC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAoB,EAAE,CAC5C,OAAO,EAAE,CAAC,gBAAgB,CAAC,GAAG,CAC5B,CAAC,IAAI,EAAiB,EAAE,CAAC,CAAC;IACxB,IAAI,EAAE,IAAI,CAAC,IAAI;IACf,QAAQ,EAAE,IAAI,CAAC,QAAQ;IACvB,YAAY,EAAE,mBAAmB,CAAC,IAAI,CAAC,QAAQ,CAAC;CACjD,CAAC,CACH,CAAC;AAEJ;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,EAAE,GAAY,EAA0B,EAAE;IAC1E,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,GAAG,IAAI,GAAG,EAAE,CAAC,CAAC;IACtD,MAAM,cAAc,GAAG,OAAO,EAAE,CAAC;IACjC,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;IACzB,IAAI,YAAuC,CAAC;IAE5C,wCAAwC;IACxC,KAAK,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CACxC,cAAc,CAAC,mBAAmB,CAAC,UAAU,CAC9C,EAAE,CAAC;QACF,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QACnC,IAAI,OAAO,CAAC,QAAQ,KAAK,IAAI;YAAE,SAAS;QACxC,YAAY,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC;QAC/D,IAAI,YAAY;YAAE,MAAM;IAC1B,CAAC;IAED,IAAI,CAAC,YAAY;QAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC9D,OAAO,YAAY,CAAC;AACtB,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,OAAe,EAAU,EAAE,CAC7D,IAAI,CAAC,cAAc,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE,eAAe,CAAC,CAAC;AAE/D;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAW,EAAE,CAC9C,IAAI,CAAC,cAAc,EAAE,EAAE,eAAe,CAAC,CAAC","sourcesContent":["import { join } from \"node:path\";\nimport { VSCodeProfile } from \"../types/types.vscode.js\";\nimport { storage } from \"./vscode.storage.js\";\nimport { configUserPath } from \"./vscode.config.js\";\nimport { findWorkspaceRoot } from \"../workspace/workspace.common.js\";\nimport { cwd } from \"node:process\";\n\n/**\n * Returns all VS Code user-data profiles.\n *\n * @remarks\n * Each profile is resolved from the persisted {@link storage} and enriched\n * with the absolute path to its `settings.json` via {@link profileSettingsPath}.\n *\n * @returns An array of {@link VSCodeProfile} objects for every configured profile.\n */\nexport const profiles = (): VSCodeProfile[] =>\n  storage().userDataProfiles.map(\n    (prof): VSCodeProfile => ({\n      name: prof.name,\n      location: prof.location,\n      settingsPath: profileSettingsPath(prof.location),\n    }),\n  );\n\n/**\n * Resolves the active VS Code profile for a given workspace directory.\n *\n * @remarks\n * The workspace root is located via {@link findWorkspaceRoot}, then matched\n * against the profile-to-workspace associations stored in VS Code's\n * `storage.json`. Throws if no matching profile is found.\n *\n * @param dir - The directory to resolve the workspace from. Defaults to the\n *   current working directory.\n * @returns A promise that resolves to the active {@link VSCodeProfile}.\n * @throws If no active profile is associated with the resolved workspace.\n */\nexport const activeProfile = async (dir?: string): Promise<VSCodeProfile> => {\n  const foundWS = await findWorkspaceRoot(dir ?? cwd());\n  const storageContent = storage();\n  const profs = profiles();\n  let foundProfile: VSCodeProfile | undefined;\n\n  // eslint-disable-next-line prefer-const\n  for (let [path, profile] of Object.entries(\n    storageContent.profileAssociations.workspaces,\n  )) {\n    path = path.replace(\"file://\", \"\");\n    if (foundWS.filePath !== path) continue;\n    foundProfile = profs.find((prof) => prof.location === profile);\n    if (foundProfile) break;\n  }\n\n  if (!foundProfile) throw new Error(\"No active profile found\");\n  return foundProfile;\n};\n\n/**\n * Builds the absolute path to a profile's `settings.json` file.\n *\n * @param profile - The unique location identifier of the profile.\n * @returns The absolute path to `settings.json` inside the profile's directory.\n */\nexport const profileSettingsPath = (profile: string): string =>\n  join(configUserPath(), \"profiles\", profile, \"settings.json\");\n\n/**\n * Returns the absolute path to the default (global) `settings.json` file.\n *\n * @remarks\n * This is the settings file used when no named profile is active.\n *\n * @returns The absolute path to the default `settings.json` in the VS Code\n *   `User` directory.\n */\nexport const defaultSettingsPath = (): string =>\n  join(configUserPath(), \"settings.json\");\n"]}

package/dist/vscode/vscode.settings.d.ts

@@ -1,6 +1,31 @@
 import { VSCodeSettings } from "../types/types.vscode.js";
+/**
+ * Reads and returns the VS Code `settings.json` for the active profile.
+ *
+ * @remarks
+ * The result is cached after the first successful read. If no active profile
+ * can be resolved, the default (global) settings file is used as a fallback.
+ * A shallow copy is returned so that callers cannot mutate the cached object.
+ *
+ * @param dir - Optional directory used to resolve the active profile's
+ *   workspace. Defaults to the current working directory.
+ * @returns A promise that resolves to a shallow copy of the parsed
+ *   {@link VSCodeSettings}.
+ * @throws If the settings file cannot be read or parsed.
+ */
 export declare const vscodeSettings: (dir?: string) => Promise<VSCodeSettings>;
+/**
+ * Extracts the `C_Cpp.clang_format_style` value from the VS Code settings.
+ *
+ * @param cwd - The working directory used to locate the active profile's settings.
+ * @returns A promise that resolves to the clang-format style string.
+ * @throws If the `C_Cpp.clang_format_style` key is missing from the settings.
+ */
 export declare const clangFormatStyle: (cwd: string) => Promise<string>;
-/** @internal test-only */
+/**
+ * Resets the cached settings so they are re-read on the next call.
+ *
+ * @internal
+ */
 export declare const __resetSettings: () => void;
 //# sourceMappingURL=vscode.settings.d.ts.map

package/dist/vscode/vscode.settings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vscode.settings.d.ts","sourceRoot":"","sources":["../../src/vscode/vscode.settings.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAO1D,eAAO,MAAM,cAAc,GAAU,MAAM,MAAM,KAAG,OAAO,CAAC,cAAc,CAgBzE,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAU,KAAK,MAAM,KAAG,OAAO,CAAC,MAAM,CAKlE,CAAC;AAEF,0BAA0B;AAC1B,eAAO,MAAM,eAAe,YAE3B,CAAC"}
+{"version":3,"file":"vscode.settings.d.ts","sourceRoot":"","sources":["../../src/vscode/vscode.settings.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAO1D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,GAAU,MAAM,MAAM,KAAG,OAAO,CAAC,cAAc,CAgBzE,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAU,KAAK,MAAM,KAAG,OAAO,CAAC,MAAM,CAKlE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,YAE3B,CAAC"}

package/dist/vscode/vscode.settings.js

@@ -2,6 +2,20 @@ import { activeProfile, defaultSettingsPath } from "./vscode.profiles.js";
 import { readFile } from "node:fs/promises";
 import json5 from "json5";
 let __settings = null;
+/**
+ * Reads and returns the VS Code `settings.json` for the active profile.
+ *
+ * @remarks
+ * The result is cached after the first successful read. If no active profile
+ * can be resolved, the default (global) settings file is used as a fallback.
+ * A shallow copy is returned so that callers cannot mutate the cached object.
+ *
+ * @param dir - Optional directory used to resolve the active profile's
+ *   workspace. Defaults to the current working directory.
+ * @returns A promise that resolves to a shallow copy of the parsed
+ *   {@link VSCodeSettings}.
+ * @throws If the settings file cannot be read or parsed.
+ */
 export const vscodeSettings = async (dir) => {
     if (!__settings) {
         let settingsPath;
@@ -18,13 +32,24 @@ export const vscodeSettings = async (dir) => {
     }
     return { ...__settings };
 };
+/**
+ * Extracts the `C_Cpp.clang_format_style` value from the VS Code settings.
+ *
+ * @param cwd - The working directory used to locate the active profile's settings.
+ * @returns A promise that resolves to the clang-format style string.
+ * @throws If the `C_Cpp.clang_format_style` key is missing from the settings.
+ */
 export const clangFormatStyle = async (cwd) => {
     const settings = await vscodeSettings(cwd);
     if (!("C_Cpp.clang_format_style" in settings))
         throw new Error("C_Cpp.clang_format_style not found in settings.json");
     return settings["C_Cpp.clang_format_style"];
 };
-/** @internal test-only */
+/**
+ * Resets the cached settings so they are re-read on the next call.
+ *
+ * @internal
+ */
 export const __resetSettings = () => {
     __settings = null;
 };

package/dist/vscode/vscode.settings.js.map

@@ -1 +1 @@
-{"version":3,"file":"vscode.settings.js","sourceRoot":"","sources":["../../src/vscode/vscode.settings.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,IAAI,UAAU,GAA0B,IAAI,CAAC;AAE7C,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,EAAE,GAAY,EAA2B,EAAE;IAC5E,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,IAAI,YAAgC,CAAC;QAErC,IAAI,CAAC;YACH,YAAY,GAAG,CAAC,MAAM,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC;QACzD,CAAC;QAAC,MAAM,CAAC;YACP,YAAY,GAAG,mBAAmB,EAAE,CAAC;QACvC,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QAClD,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,CAAC,UAAU;YAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;IACxD,CAAC;IAED,OAAO,EAAE,GAAG,UAAU,EAAE,CAAC;AAC3B,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,EAAE,GAAW,EAAmB,EAAE;IACrE,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,GAAG,CAAC,CAAC;IAC3C,IAAI,CAAC,CAAC,0BAA0B,IAAI,QAAQ,CAAC;QAC3C,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,OAAO,QAAQ,CAAC,0BAA0B,CAAW,CAAC;AACxD,CAAC,CAAC;AAEF,0BAA0B;AAC1B,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,EAAE;IAClC,UAAU,GAAG,IAAI,CAAC;AACpB,CAAC,CAAC","sourcesContent":["import { VSCodeSettings } from \"../types/types.vscode.js\";\nimport { activeProfile, defaultSettingsPath } from \"./vscode.profiles.js\";\nimport { readFile } from \"node:fs/promises\";\nimport json5 from \"json5\";\n\nlet __settings: VSCodeSettings | null = null;\n\nexport const vscodeSettings = async (dir?: string): Promise<VSCodeSettings> => {\n  if (!__settings) {\n    let settingsPath: string | undefined;\n\n    try {\n      settingsPath = (await activeProfile(dir)).settingsPath;\n    } catch {\n      settingsPath = defaultSettingsPath();\n    }\n\n    const raw = await readFile(settingsPath, \"utf-8\");\n    __settings = json5.parse(raw);\n    if (!__settings) throw new Error(\"No settings found\");\n  }\n\n  return { ...__settings };\n};\n\nexport const clangFormatStyle = async (cwd: string): Promise<string> => {\n  const settings = await vscodeSettings(cwd);\n  if (!(\"C_Cpp.clang_format_style\" in settings))\n    throw new Error(\"C_Cpp.clang_format_style not found in settings.json\");\n  return settings[\"C_Cpp.clang_format_style\"] as string;\n};\n\n/** @internal test-only */\nexport const __resetSettings = () => {\n  __settings = null;\n};\n"]}
+{"version":3,"file":"vscode.settings.js","sourceRoot":"","sources":["../../src/vscode/vscode.settings.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,IAAI,UAAU,GAA0B,IAAI,CAAC;AAE7C;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,EAAE,GAAY,EAA2B,EAAE;IAC5E,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,IAAI,YAAgC,CAAC;QAErC,IAAI,CAAC;YACH,YAAY,GAAG,CAAC,MAAM,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC;QACzD,CAAC;QAAC,MAAM,CAAC;YACP,YAAY,GAAG,mBAAmB,EAAE,CAAC;QACvC,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QAClD,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,CAAC,UAAU;YAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;IACxD,CAAC;IAED,OAAO,EAAE,GAAG,UAAU,EAAE,CAAC;AAC3B,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,EAAE,GAAW,EAAmB,EAAE;IACrE,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,GAAG,CAAC,CAAC;IAC3C,IAAI,CAAC,CAAC,0BAA0B,IAAI,QAAQ,CAAC;QAC3C,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,OAAO,QAAQ,CAAC,0BAA0B,CAAW,CAAC;AACxD,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,EAAE;IAClC,UAAU,GAAG,IAAI,CAAC;AACpB,CAAC,CAAC","sourcesContent":["import { VSCodeSettings } from \"../types/types.vscode.js\";\nimport { activeProfile, defaultSettingsPath } from \"./vscode.profiles.js\";\nimport { readFile } from \"node:fs/promises\";\nimport json5 from \"json5\";\n\nlet __settings: VSCodeSettings | null = null;\n\n/**\n * Reads and returns the VS Code `settings.json` for the active profile.\n *\n * @remarks\n * The result is cached after the first successful read. If no active profile\n * can be resolved, the default (global) settings file is used as a fallback.\n * A shallow copy is returned so that callers cannot mutate the cached object.\n *\n * @param dir - Optional directory used to resolve the active profile's\n *   workspace. Defaults to the current working directory.\n * @returns A promise that resolves to a shallow copy of the parsed\n *   {@link VSCodeSettings}.\n * @throws If the settings file cannot be read or parsed.\n */\nexport const vscodeSettings = async (dir?: string): Promise<VSCodeSettings> => {\n  if (!__settings) {\n    let settingsPath: string | undefined;\n\n    try {\n      settingsPath = (await activeProfile(dir)).settingsPath;\n    } catch {\n      settingsPath = defaultSettingsPath();\n    }\n\n    const raw = await readFile(settingsPath, \"utf-8\");\n    __settings = json5.parse(raw);\n    if (!__settings) throw new Error(\"No settings found\");\n  }\n\n  return { ...__settings };\n};\n\n/**\n * Extracts the `C_Cpp.clang_format_style` value from the VS Code settings.\n *\n * @param cwd - The working directory used to locate the active profile's settings.\n * @returns A promise that resolves to the clang-format style string.\n * @throws If the `C_Cpp.clang_format_style` key is missing from the settings.\n */\nexport const clangFormatStyle = async (cwd: string): Promise<string> => {\n  const settings = await vscodeSettings(cwd);\n  if (!(\"C_Cpp.clang_format_style\" in settings))\n    throw new Error(\"C_Cpp.clang_format_style not found in settings.json\");\n  return settings[\"C_Cpp.clang_format_style\"] as string;\n};\n\n/**\n * Resets the cached settings so they are re-read on the next call.\n *\n * @internal\n */\nexport const __resetSettings = () => {\n  __settings = null;\n};\n"]}

package/dist/vscode/vscode.storage.d.ts

@@ -1,6 +1,26 @@
 import { VSCodeStorage } from "../types/types.vscode.js";
+/**
+ * Returns the absolute path to the VS Code `storage.json` file.
+ *
+ * @returns The path to `storage.json` inside the `globalStorage` directory.
+ */
 export declare const storagePath: () => string;
+/**
+ * Reads and returns the parsed VS Code `storage.json`.
+ *
+ * @remarks
+ * The result is cached after the first successful read. Subsequent calls
+ * return the cached {@link VSCodeStorage} instance without re-reading
+ * the file from disk.
+ *
+ * @returns The parsed {@link VSCodeStorage} object.
+ * @throws If the file cannot be read or parsed.
+ */
 export declare const storage: () => VSCodeStorage;
-/** @internal test-only */
+/**
+ * Resets the cached storage so it is re-read on the next call.
+ *
+ * @internal
+ */
 export declare const __resetStorage: () => void;
 //# sourceMappingURL=vscode.storage.d.ts.map

package/dist/vscode/vscode.storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vscode.storage.d.ts","sourceRoot":"","sources":["../../src/vscode/vscode.storage.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAGzD,eAAO,MAAM,WAAW,QAAO,MAC0B,CAAC;AAG1D,eAAO,MAAM,OAAO,QAAO,aAM1B,CAAC;AAEF,0BAA0B;AAC1B,eAAO,MAAM,cAAc,YAE1B,CAAC"}
+{"version":3,"file":"vscode.storage.d.ts","sourceRoot":"","sources":["../../src/vscode/vscode.storage.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAGzD;;;;GAIG;AACH,eAAO,MAAM,WAAW,QAAO,MAC0B,CAAC;AAI1D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,OAAO,QAAO,aAM1B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,YAE1B,CAAC"}

package/dist/vscode/vscode.storage.js

@@ -2,8 +2,24 @@ import * as fs from "node:fs";
 import { join } from "node:path";
 import json5 from "json5";
 import { configUserPath } from "./vscode.config.js";
+/**
+ * Returns the absolute path to the VS Code `storage.json` file.
+ *
+ * @returns The path to `storage.json` inside the `globalStorage` directory.
+ */
 export const storagePath = () => join(configUserPath(), "globalStorage", "storage.json");
 let __storage;
+/**
+ * Reads and returns the parsed VS Code `storage.json`.
+ *
+ * @remarks
+ * The result is cached after the first successful read. Subsequent calls
+ * return the cached {@link VSCodeStorage} instance without re-reading
+ * the file from disk.
+ *
+ * @returns The parsed {@link VSCodeStorage} object.
+ * @throws If the file cannot be read or parsed.
+ */
 export const storage = () => {
     if (__storage)
         return __storage;
@@ -13,7 +29,11 @@ export const storage = () => {
         throw new Error("VS Code storage.json could not be loaded");
     return __storage;
 };
-/** @internal test-only */
+/**
+ * Resets the cached storage so it is re-read on the next call.
+ *
+ * @internal
+ */
 export const __resetStorage = () => {
     __storage = undefined;
 };

package/dist/vscode/vscode.storage.js.map

@@ -1 +1 @@
-{"version":3,"file":"vscode.storage.js","sourceRoot":"","sources":["../../src/vscode/vscode.storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,MAAM,CAAC,MAAM,WAAW,GAAG,GAAW,EAAE,CACtC,IAAI,CAAC,cAAc,EAAE,EAAE,eAAe,EAAE,cAAc,CAAC,CAAC;AAE1D,IAAI,SAAoC,CAAC;AACzC,MAAM,CAAC,MAAM,OAAO,GAAG,GAAkB,EAAE;IACzC,IAAI,SAAS;QAAE,OAAO,SAAS,CAAC;IAChC,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC1D,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACjC,IAAI,CAAC,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC5E,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC;AAEF,0BAA0B;AAC1B,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,EAAE;IACjC,SAAS,GAAG,SAAS,CAAC;AACxB,CAAC,CAAC","sourcesContent":["import * as fs from \"node:fs\";\nimport { join } from \"node:path\";\nimport json5 from \"json5\";\nimport { VSCodeStorage } from \"../types/types.vscode.js\";\nimport { configUserPath } from \"./vscode.config.js\";\n\nexport const storagePath = (): string =>\n  join(configUserPath(), \"globalStorage\", \"storage.json\");\n\nlet __storage: VSCodeStorage | undefined;\nexport const storage = (): VSCodeStorage => {\n  if (__storage) return __storage;\n  const content = fs.readFileSync(storagePath()).toString();\n  __storage = json5.parse(content);\n  if (!__storage) throw new Error(\"VS Code storage.json could not be loaded\");\n  return __storage;\n};\n\n/** @internal test-only */\nexport const __resetStorage = () => {\n  __storage = undefined;\n};\n"]}
+{"version":3,"file":"vscode.storage.js","sourceRoot":"","sources":["../../src/vscode/vscode.storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,GAAW,EAAE,CACtC,IAAI,CAAC,cAAc,EAAE,EAAE,eAAe,EAAE,cAAc,CAAC,CAAC;AAE1D,IAAI,SAAoC,CAAC;AAEzC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,GAAkB,EAAE;IACzC,IAAI,SAAS;QAAE,OAAO,SAAS,CAAC;IAChC,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC1D,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACjC,IAAI,CAAC,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC5E,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,EAAE;IACjC,SAAS,GAAG,SAAS,CAAC;AACxB,CAAC,CAAC","sourcesContent":["import * as fs from \"node:fs\";\nimport { join } from \"node:path\";\nimport json5 from \"json5\";\nimport { VSCodeStorage } from \"../types/types.vscode.js\";\nimport { configUserPath } from \"./vscode.config.js\";\n\n/**\n * Returns the absolute path to the VS Code `storage.json` file.\n *\n * @returns The path to `storage.json` inside the `globalStorage` directory.\n */\nexport const storagePath = (): string =>\n  join(configUserPath(), \"globalStorage\", \"storage.json\");\n\nlet __storage: VSCodeStorage | undefined;\n\n/**\n * Reads and returns the parsed VS Code `storage.json`.\n *\n * @remarks\n * The result is cached after the first successful read. Subsequent calls\n * return the cached {@link VSCodeStorage} instance without re-reading\n * the file from disk.\n *\n * @returns The parsed {@link VSCodeStorage} object.\n * @throws If the file cannot be read or parsed.\n */\nexport const storage = (): VSCodeStorage => {\n  if (__storage) return __storage;\n  const content = fs.readFileSync(storagePath()).toString();\n  __storage = json5.parse(content);\n  if (!__storage) throw new Error(\"VS Code storage.json could not be loaded\");\n  return __storage;\n};\n\n/**\n * Resets the cached storage so it is re-read on the next call.\n *\n * @internal\n */\nexport const __resetStorage = () => {\n  __storage = undefined;\n};\n"]}

package/dist/vscode/vscode.workspace.d.ts

@@ -1,4 +1,21 @@
 import { VSCodeWorkspace } from "../types/types.vscode.js";
+/**
+ * Reads and returns a parsed VS Code `.code-workspace` file.
+ *
+ * @remarks
+ * The result is cached per `workspaceFile` path. A shallow copy is returned
+ * so that callers cannot mutate the cached object.
+ *
+ * @param workspaceFile - Absolute path to the `.code-workspace` file.
+ * @returns A promise that resolves to a shallow copy of the parsed
+ *   {@link VSCodeWorkspace}.
+ */
 export declare const vscodeWorkspace: (workspaceFile: string) => Promise<VSCodeWorkspace>;
+/**
+ * Returns the directory that contains the given workspace file.
+ *
+ * @param workspaceFile - Absolute path to the `.code-workspace` file.
+ * @returns The parent directory of the workspace file.
+ */
 export declare const vscodeWorkspaceRoot: (workspaceFile: string) => string;
 //# sourceMappingURL=vscode.workspace.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"vscode.workspace.d.ts","sourceRoot":"","sources":["../../src/vscode/vscode.workspace.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAM3D,eAAO,MAAM,eAAe,GAC1B,eAAe,MAAM,KACpB,OAAO,CAAC,eAAe,CASzB,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAAI,eAAe,MAAM,WACjC,CAAC"}
+{"version":3,"file":"vscode.workspace.d.ts","sourceRoot":"","sources":["../../src/vscode/vscode.workspace.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAM3D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,GAC1B,eAAe,MAAM,KACpB,OAAO,CAAC,eAAe,CASzB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,eAAe,MAAM,WACjC,CAAC"}

package/dist/vscode/vscode.workspace.js

@@ -2,6 +2,17 @@ import { readFile } from "node:fs/promises";
 import json5 from "json5";
 import { dirname } from "node:path";
 const __workspaces = {};
+/**
+ * Reads and returns a parsed VS Code `.code-workspace` file.
+ *
+ * @remarks
+ * The result is cached per `workspaceFile` path. A shallow copy is returned
+ * so that callers cannot mutate the cached object.
+ *
+ * @param workspaceFile - Absolute path to the `.code-workspace` file.
+ * @returns A promise that resolves to a shallow copy of the parsed
+ *   {@link VSCodeWorkspace}.
+ */
 export const vscodeWorkspace = async (workspaceFile) => {
     let found = __workspaces[workspaceFile];
     if (!found) {
@@ -11,5 +22,11 @@ export const vscodeWorkspace = async (workspaceFile) => {
     }
     return { ...found };
 };
+/**
+ * Returns the directory that contains the given workspace file.
+ *
+ * @param workspaceFile - Absolute path to the `.code-workspace` file.
+ * @returns The parent directory of the workspace file.
+ */
 export const vscodeWorkspaceRoot = (workspaceFile) => dirname(workspaceFile);
 //# sourceMappingURL=vscode.workspace.js.map

package/dist/vscode/vscode.workspace.js.map

@@ -1 +1 @@
-{"version":3,"file":"vscode.workspace.js","sourceRoot":"","sources":["../../src/vscode/vscode.workspace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,YAAY,GAAoC,EAAE,CAAC;AAEzD,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,EAClC,aAAqB,EACK,EAAE;IAC5B,IAAI,KAAK,GAAG,YAAY,CAAC,aAAa,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;QACnD,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACzB,YAAY,CAAC,aAAa,CAAC,GAAG,KAAK,CAAC;IACtC,CAAC;IAED,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC;AACtB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,aAAqB,EAAE,EAAE,CAC3D,OAAO,CAAC,aAAa,CAAC,CAAC","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { VSCodeWorkspace } from \"../types/types.vscode.js\";\nimport json5 from \"json5\";\nimport { dirname } from \"node:path\";\n\nconst __workspaces: Record<string, VSCodeWorkspace> = {};\n\nexport const vscodeWorkspace = async (\n  workspaceFile: string,\n): Promise<VSCodeWorkspace> => {\n  let found = __workspaces[workspaceFile];\n  if (!found) {\n    const raw = await readFile(workspaceFile, \"utf-8\");\n    found = json5.parse(raw);\n    __workspaces[workspaceFile] = found;\n  }\n\n  return { ...found };\n};\n\nexport const vscodeWorkspaceRoot = (workspaceFile: string) =>\n  dirname(workspaceFile);\n"]}
+{"version":3,"file":"vscode.workspace.js","sourceRoot":"","sources":["../../src/vscode/vscode.workspace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,YAAY,GAAoC,EAAE,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,EAClC,aAAqB,EACK,EAAE;IAC5B,IAAI,KAAK,GAAG,YAAY,CAAC,aAAa,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;QACnD,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACzB,YAAY,CAAC,aAAa,CAAC,GAAG,KAAK,CAAC;IACtC,CAAC;IAED,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC;AACtB,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,aAAqB,EAAE,EAAE,CAC3D,OAAO,CAAC,aAAa,CAAC,CAAC","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { VSCodeWorkspace } from \"../types/types.vscode.js\";\nimport json5 from \"json5\";\nimport { dirname } from \"node:path\";\n\nconst __workspaces: Record<string, VSCodeWorkspace> = {};\n\n/**\n * Reads and returns a parsed VS Code `.code-workspace` file.\n *\n * @remarks\n * The result is cached per `workspaceFile` path. A shallow copy is returned\n * so that callers cannot mutate the cached object.\n *\n * @param workspaceFile - Absolute path to the `.code-workspace` file.\n * @returns A promise that resolves to a shallow copy of the parsed\n *   {@link VSCodeWorkspace}.\n */\nexport const vscodeWorkspace = async (\n  workspaceFile: string,\n): Promise<VSCodeWorkspace> => {\n  let found = __workspaces[workspaceFile];\n  if (!found) {\n    const raw = await readFile(workspaceFile, \"utf-8\");\n    found = json5.parse(raw);\n    __workspaces[workspaceFile] = found;\n  }\n\n  return { ...found };\n};\n\n/**\n * Returns the directory that contains the given workspace file.\n *\n * @param workspaceFile - Absolute path to the `.code-workspace` file.\n * @returns The parent directory of the workspace file.\n */\nexport const vscodeWorkspaceRoot = (workspaceFile: string) =>\n  dirname(workspaceFile);\n"]}

package/dist/workspace/Workspace.d.ts

@@ -1,24 +1,109 @@
 import { PnpmWorkspace } from "../types/types.workspace.js";
 import { Pkg } from "../pkg/Pkg.js";
+/**
+ * Create and register the global {@link Workspace} singleton.
+ *
+ * @remarks
+ * This is the primary entry point for bootstrapping a workspace. It must be
+ * called before {@link workspace} can be used. Subsequent calls replace the
+ * existing singleton.
+ *
+ * @param repoRoot - Absolute path to the repository root directory.
+ * @returns The newly created {@link Workspace} instance.
+ *
+ * @example
+ * ```ts
+ * const ws = initWorkspace("/path/to/repo");
+ * await ws.read();
+ * console.log(ws.packages);
+ * ```
+ */
 export declare const initWorkspace: (repoRoot: string) => Workspace;
+/**
+ * Retrieve the global {@link Workspace} singleton.
+ *
+ * @remarks
+ * Throws if {@link initWorkspace} has not been called first.
+ *
+ * @returns The current {@link Workspace} instance.
+ *
+ * @example
+ * ```ts
+ * const ws = workspace();
+ * console.log(ws.rootPackage.name);
+ * ```
+ */
 export declare const workspace: () => Workspace;
 interface WorkspaceData {
     pnpmWs: PnpmWorkspace;
     rootPackage: Pkg;
     packages: Pkg[];
 }
+/**
+ * Represents a pnpm monorepo workspace rooted at a given directory.
+ *
+ * @remarks
+ * {@link Workspace} is implemented as a singleton managed via the
+ * {@link initWorkspace} and {@link workspace} helper functions. It lazily
+ * reads the `pnpm-workspace.yaml` and every package's `package.json` on the
+ * first call to {@link Workspace.read}, and persists pending changes back to
+ * disk with {@link Workspace.write}.
+ */
 export declare class Workspace {
     readonly repoRoot: string;
     protected _data: WorkspaceData | null;
+    /**
+     * Create and register a new singleton instance.
+     *
+     * @internal
+     * @param repoRoot - Absolute path to the repository root directory.
+     * @returns The newly created {@link Workspace} instance.
+     */
     static __init(repoRoot: string): Workspace;
+    /**
+     * Return the current singleton instance.
+     *
+     * @internal
+     * @returns The existing {@link Workspace} instance.
+     * @throws {Error} If the singleton has not been initialised via {@link Workspace.__init}.
+     */
     static __get(): Workspace;
     private constructor();
+    /**
+     * A deep-cloned copy of the parsed `pnpm-workspace.yaml` configuration.
+     *
+     * @remarks
+     * Returns a clone so that callers cannot mutate the internal state.
+     */
     get pnpmWs(): PnpmWorkspace;
+    /**
+     * The list of {@link Pkg} instances representing each workspace package.
+     */
     get packages(): Pkg[];
+    /**
+     * The {@link Pkg} instance for the repository root `package.json`.
+     */
     get rootPackage(): Pkg;
     protected set data(c: WorkspaceData);
     protected get data(): WorkspaceData;
+    /**
+     * Read the workspace configuration and all package manifests from disk.
+     *
+     * @remarks
+     * This method is idempotent — if data has already been loaded it returns
+     * immediately without re-reading. It parses `pnpm-workspace.yaml`, then
+     * reads every referenced `package.json` in parallel.
+     *
+     * @returns This {@link Workspace} instance for chaining.
+     */
     read(): Promise<Workspace>;
+    /**
+     * Persist all modified package manifests back to disk.
+     *
+     * @remarks
+     * No-ops if {@link Workspace.read} has not yet been called. Writes the
+     * root package and every workspace package in parallel.
+     */
     write(): Promise<void>;
 }
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"Workspace.d.ts","sourceRoot":"","sources":["../../src/workspace/Workspace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAE5D,OAAO,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAKpC,eAAO,MAAM,aAAa,GAAI,UAAU,MAAM,cAA+B,CAAC;AAC9E,eAAO,MAAM,SAAS,iBAA0B,CAAC;AAEjD,UAAU,aAAa;IACrB,MAAM,EAAE,aAAa,CAAC;IACtB,WAAW,EAAE,GAAG,CAAC;IACjB,QAAQ,EAAE,GAAG,EAAE,CAAC;CACjB;AAED,qBAAa,SAAS;aAagB,QAAQ,EAAE,MAAM;IAZpD,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAQ;WAE/B,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS;WAInC,KAAK,IAAI,SAAS;IAMhC,OAAO;IAEP,IAAW,MAAM,IAAI,aAAa,CAEjC;IAED,IAAW,QAAQ,IAAI,GAAG,EAAE,CAE3B;IAED,IAAW,WAAW,IAAI,GAAG,CAE5B;IAED,SAAS,KAAK,IAAI,CAAC,CAAC,EAAE,aAAa,EAElC;IAED,SAAS,KAAK,IAAI,IAAI,aAAa,CAGlC;IAEY,IAAI,IAAI,OAAO,CAAC,SAAS,CAAC;IAqB1B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAOpC"}
+{"version":3,"file":"Workspace.d.ts","sourceRoot":"","sources":["../../src/workspace/Workspace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAE5D,OAAO,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAKpC;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,aAAa,GAAI,UAAU,MAAM,cAA+B,CAAC;AAE9E;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,SAAS,iBAA0B,CAAC;AAEjD,UAAU,aAAa;IACrB,MAAM,EAAE,aAAa,CAAC;IACtB,WAAW,EAAE,GAAG,CAAC;IACjB,QAAQ,EAAE,GAAG,EAAE,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,qBAAa,SAAS;aA2BgB,QAAQ,EAAE,MAAM;IA1BpD,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAQ;IAE7C;;;;;;OAMG;WACW,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS;IAIjD;;;;;;OAMG;WACW,KAAK,IAAI,SAAS;IAMhC,OAAO;IAEP;;;;;OAKG;IACH,IAAW,MAAM,IAAI,aAAa,CAEjC;IAED;;OAEG;IACH,IAAW,QAAQ,IAAI,GAAG,EAAE,CAE3B;IAED;;OAEG;IACH,IAAW,WAAW,IAAI,GAAG,CAE5B;IAED,SAAS,KAAK,IAAI,CAAC,CAAC,EAAE,aAAa,EAElC;IAED,SAAS,KAAK,IAAI,IAAI,aAAa,CAGlC;IAED;;;;;;;;;OASG;IACU,IAAI,IAAI,OAAO,CAAC,SAAS,CAAC;IAqBvC;;;;;;OAMG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAOpC"}

package/dist/workspace/Workspace.js

@@ -2,14 +2,70 @@ import { readWorkspaceYaml } from "./workspace.common.js";
 import { Pkg } from "../pkg/Pkg.js";
 import { jsonClone } from "../common/common.json.js";
 let __instance = null;
+/**
+ * Create and register the global {@link Workspace} singleton.
+ *
+ * @remarks
+ * This is the primary entry point for bootstrapping a workspace. It must be
+ * called before {@link workspace} can be used. Subsequent calls replace the
+ * existing singleton.
+ *
+ * @param repoRoot - Absolute path to the repository root directory.
+ * @returns The newly created {@link Workspace} instance.
+ *
+ * @example
+ * ```ts
+ * const ws = initWorkspace("/path/to/repo");
+ * await ws.read();
+ * console.log(ws.packages);
+ * ```
+ */
 export const initWorkspace = (repoRoot) => Workspace.__init(repoRoot);
+/**
+ * Retrieve the global {@link Workspace} singleton.
+ *
+ * @remarks
+ * Throws if {@link initWorkspace} has not been called first.
+ *
+ * @returns The current {@link Workspace} instance.
+ *
+ * @example
+ * ```ts
+ * const ws = workspace();
+ * console.log(ws.rootPackage.name);
+ * ```
+ */
 export const workspace = () => Workspace.__get();
+/**
+ * Represents a pnpm monorepo workspace rooted at a given directory.
+ *
+ * @remarks
+ * {@link Workspace} is implemented as a singleton managed via the
+ * {@link initWorkspace} and {@link workspace} helper functions. It lazily
+ * reads the `pnpm-workspace.yaml` and every package's `package.json` on the
+ * first call to {@link Workspace.read}, and persists pending changes back to
+ * disk with {@link Workspace.write}.
+ */
 export class Workspace {
     repoRoot;
     _data = null;
+    /**
+     * Create and register a new singleton instance.
+     *
+     * @internal
+     * @param repoRoot - Absolute path to the repository root directory.
+     * @returns The newly created {@link Workspace} instance.
+     */
     static __init(repoRoot) {
         return (__instance = new Workspace(repoRoot));
     }
+    /**
+     * Return the current singleton instance.
+     *
+     * @internal
+     * @returns The existing {@link Workspace} instance.
+     * @throws {Error} If the singleton has not been initialised via {@link Workspace.__init}.
+     */
     static __get() {
         if (!__instance)
             throw new Error("Workspace not initialized. initWorkspace()");
@@ -18,12 +74,24 @@ export class Workspace {
     constructor(repoRoot) {
         this.repoRoot = repoRoot;
     }
+    /**
+     * A deep-cloned copy of the parsed `pnpm-workspace.yaml` configuration.
+     *
+     * @remarks
+     * Returns a clone so that callers cannot mutate the internal state.
+     */
     get pnpmWs() {
         return jsonClone(this.data.pnpmWs);
     }
+    /**
+     * The list of {@link Pkg} instances representing each workspace package.
+     */
     get packages() {
         return this.data.packages;
     }
+    /**
+     * The {@link Pkg} instance for the repository root `package.json`.
+     */
     get rootPackage() {
         return this.data.rootPackage;
     }
@@ -35,6 +103,16 @@ export class Workspace {
             throw new Error(`Data not loaded. ${this.repoRoot}`);
         return this._data;
     }
+    /**
+     * Read the workspace configuration and all package manifests from disk.
+     *
+     * @remarks
+     * This method is idempotent — if data has already been loaded it returns
+     * immediately without re-reading. It parses `pnpm-workspace.yaml`, then
+     * reads every referenced `package.json` in parallel.
+     *
+     * @returns This {@link Workspace} instance for chaining.
+     */
     async read() {
         if (this._data)
             return this;
@@ -52,6 +130,13 @@ export class Workspace {
         };
         return this;
     }
+    /**
+     * Persist all modified package manifests back to disk.
+     *
+     * @remarks
+     * No-ops if {@link Workspace.read} has not yet been called. Writes the
+     * root package and every workspace package in parallel.
+     */
     async write() {
         if (!this._data)
             return;