@orkestrel/scaffold 0.0.46 → 0.0.48

package/dist/src/core/index.d.cts

@@ -1060,7 +1060,7 @@ export declare class Compiler implements CompilerInterface {
               conformance: "// Where this package drifts from the official tooling it stays compatible with.\n// The subject is this package, so the proof is hermetic and stays in `npm test`.\nexport const conformance = (options?: UserConfig): UserConfig =>\n\tmergeConfig(\n\t\t{\n\t\t\tresolve,\n\t\t\ttest: {\n\t\t\t\tname: { label: 'conformance', color: 'magenta' },\n\t\t\t\tinclude: ['tests/conformance.test.ts'],\n\t\t\t\tsetupFiles: ['./tests/setup.ts'],\n\t\t\t\tenvironment: 'node',\n\t\t\t\tbrowser: { enabled: false },\n\t\t\t},\n\t\t},\n\t\toptions ?? {},\n\t)\n";
               service: "// The live external services this package drives. It starts nothing itself:\n// `scripts/service.sh` provisions, `tests/setupService.ts` proves readiness, and\n// the project stays out of `npm test` because a real service answers it.\nexport const service = (options?: UserConfig): UserConfig =>\n\tmergeConfig(\n\t\t{\n\t\t\tresolve,\n\t\t\ttest: {\n\t\t\t\tname: { label: 'service', color: 'red' },\n\t\t\t\tinclude: ['tests/service/**/*.test.ts'],\n\t\t\t\tsetupFiles: ['./tests/setup.ts', './tests/setupService.ts'],\n\t\t\t\tenvironment: 'node',\n\t\t\t\tbrowser: { enabled: false },\n\t\t\t\ttestTimeout: 120_000,\n\t\t\t\thookTimeout: 120_000,\n\t\t\t\tfileParallelism: false,\n\t\t\t},\n\t\t},\n\t\toptions ?? {},\n\t)\n";
               distribution: "export const distribution = (options?: UserConfig): UserConfig =>\n\tmergeConfig(\n\t\t{\n\t\t\tresolve,\n\t\t\ttest: {\n\t\t\t\tname: { label: 'distribution', color: 'cyan' },\n\t\t\t\tinclude: ['tests/distribution.test.ts'],\n\t\t\t\tsetupFiles: ['./tests/setup.ts'],\n\t\t\t\tenvironment: 'node',\n\t\t\t\ttestTimeout: 120_000,\n\t\t\t\thookTimeout: 120_000,\n\t\t\t\tfileParallelism: false,\n\t\t\t},\n\t\t},\n\t\toptions ?? {},\n\t)\n";
-              probe: "// A workbench, not a proof. No gate selects this project.\nexport const probe = (options?: UserConfig): UserConfig =>\n\tmergeConfig(\n\t\t{\n\t\t\tresolve,\n\t\t\ttest: {\n\t\t\t\tname: { label: 'probe', color: 'gray' },\n\t\t\t\tinclude: ['tmp/probe/**/*.test.ts'],\n\t\t\t\tsetupFiles: ['./tests/setup.ts'],\n\t\t\t\tenvironment: 'node',\n\t\t\t\tbrowser: { enabled: false },\n\t\t\t},\n\t\t},\n\t\toptions ?? {},\n\t)\n";
+              probe: "// A workbench, not a proof. No gate selects this project. Run in test mode by the\n// `test:probe` script, it collects `tmp/probe/**/*.test.ts`. Run in benchmark mode by the\n// `test:bench` script, the same workbench also collects `tests/**/*.test.ts` for a `bench` block,\n// so a suite may carry a bench beside its ordinary tests without a second project. The mode\n// guard around each `bench` call keeps it out of test mode, so it never executes there.\nexport const probe = (options?: UserConfig): UserConfig =>\n\tmergeConfig(\n\t\t{\n\t\t\tresolve,\n\t\t\ttest: {\n\t\t\t\tname: { label: 'probe', color: 'gray' },\n\t\t\t\tinclude: ['tmp/probe/**/*.test.ts'],\n\t\t\t\tsetupFiles: ['./tests/setup.ts'],\n\t\t\t\tenvironment: 'node',\n\t\t\t\tbrowser: { enabled: false },\n\t\t\t\tfileParallelism: false,\n\t\t\t\tpool: 'threads',\n\t\t\t\tbenchmark: { include: ['tmp/probe/**/*.test.ts', 'tests/**/*.test.ts'] },\n\t\t\t},\n\t\t},\n\t\toptions ?? {},\n\t)\n";
               integration: "export const integration = (options?: UserConfig): UserConfig =>\n\tmergeConfig(\n\t\t{\n\t\t\tresolve,\n\t\t\ttest: {\n\t\t\t\tname: { label: 'integration', color: 'blue' },\n\t\t\t\tinclude: ['tests/integration.test.ts'],\n\t\t\t\tsetupFiles: ['./tests/setup.ts'],\n{{global}}\t\t\t\tenvironment: 'node',\n\t\t\t},\n\t\t},\n\t\toptions ?? {},\n\t)\n";
           }>;
           tsconfigs: Readonly<{
@@ -1283,6 +1283,29 @@ export declare class Compiler implements CompilerInterface {
        /** The registry-only semver subset accepted for a development extra's range. */
        export declare const EXTRA_RANGE_PATTERN: RegExp;
 
+       /**
+        * Extract the major component of an admitted dependency range.
+        *
+        * @param range - The candidate range text.
+        * @returns The major number, or `undefined` when the text is not a canonical
+        * major caret or an admitted full-version form.
+        *
+        * @remarks
+        * A canonical toolchain range is `^MAJOR`. Existing consumer declarations may
+        * instead carry an exact `major.minor.patch` version or that version under a
+        * caret or tilde. The projection reads those forms without deciding whether a
+        * version satisfies them; {@link matchesRange} owns that separate question.
+        *
+        * @example
+        * ```ts
+        * import { extractRangeMajor } from '@orkestrel/scaffold'
+        *
+        * extractRangeMajor('^6') // the declared major
+        * extractRangeMajor('>=6.0.0') // undefined
+        * ```
+        */
+       export declare function extractRangeMajor(range: string): number | undefined;
+
        /**
         * Extract the major, minor, and patch components of an exact version.
         *
@@ -2078,9 +2101,29 @@ export declare class Compiler implements CompilerInterface {
        /** Maximum length of one declared package range. */
        export declare const MAX_RANGE_LENGTH = 2048;
 
+       /**
+        * Maximum decoded bytes accepted from one registry response.
+        *
+        * @remarks
+        * The 2026-08-21 abbreviated-packument measurements were 8,647,138 bytes for
+        * TypeScript, 8,077,438 for Playwright, 2,315,360 for `@types/node`, 2,298,256
+        * for Vite, and 1,272,652 for Vitest. The bound leaves headroom above those
+        * registry answers.
+        */
+       export declare const MAX_REGISTRY_BYTES = 33554432;
+
        /** Maximum bytes retained across one whole plan or audit. */
        export declare const MAX_TOTAL_ARTIFACT_BYTES = 104857600;
 
+       /**
+        * Maximum decoded bytes accepted across one registry-reading call.
+        *
+        * @remarks
+        * The 2026-08-21 browser-workspace registry set measured about 24 MiB. The
+        * bound leaves headroom for that set to grow without making a call unbounded.
+        */
+       export declare const MAX_TOTAL_REGISTRY_BYTES = 100663296;
+
        /** The oldest Node version the generated toolchain supports. */
        export declare const MINIMUM_NODE_VERSION = "22.12.0";
 
@@ -2527,30 +2570,80 @@ export declare class Compiler implements CompilerInterface {
        }
 
        /**
-        * One declared dependency range measured against the registry's latest release.
+        * One declared dependency range measured against a registry release.
         *
         * @remarks
-        * A found lookup carries the version upstream reported; one that produced no
-        * answer carries the cause and no version. Whether the declared range already
-        * admits that version is not recorded, because it is a deterministic function
-        * of `range` and `latest`: a stored answer could only disagree with the
-        * fields beside it. One centralized helper decides it, and every caller reads
-        * the same decision.
+        * `range` is the declared range, and `latest` is the version the producer
+        * selected. A found lookup carries that selected version; one that produced no
+        * answer carries the cause and no selected version. `major`, when present, is
+        * the stable major named by the registry's latest tag in the same answer.
         */
        export declare type Release = {
            readonly name: string;
            readonly range: string;
            readonly lookup: 'found';
            readonly latest: string;
+           readonly major?: number;
            readonly note?: never;
        } | {
            readonly name: string;
            readonly range: string;
            readonly lookup: 'missing' | 'failed';
            readonly note: string;
+           readonly major?: number;
            readonly latest?: never;
        };
 
+       /**
+        * Replace declared dependency ranges in package manifest text.
+        *
+        * @param manifest - The manifest text to compile.
+        * @param dependencies - The declared names and replacement ranges.
+        * @returns The manifest with every matching dependency-section value replaced,
+        * or `undefined` when any name has no quoted declaration in those sections.
+        *
+        * @remarks
+        * The compiler replaces values in place instead of serializing the manifest,
+        * so description, keywords, scripts, key order, indentation, and every byte
+        * outside the named ranges survive. Every occurrence in `dependencies`,
+        * `devDependencies`, and `peerDependencies` moves, which keeps duplicate
+        * declarations aligned until the manifest's own validation reports the
+        * duplicate. An override or resolution with the same name stays untouched.
+        *
+        * @example
+        * ```ts
+        * import { replaceManifestRanges } from '@orkestrel/scaffold'
+        *
+        * const manifest = '{"devDependencies":{"typescript":"^6"}}\n'
+        * replaceManifestRanges(manifest, [{ name: 'typescript', range: '^7' }])
+        * // the manifest with the declared range replaced
+        * ```
+        */
+       export declare function replaceManifestRanges(manifest: string, dependencies: readonly Dependency[]): string | undefined;
+
+       /**
+        * Replace dependency ranges in a plan's manifest and recompute its identity.
+        *
+        * @param plan - The plan carrying the manifest artifact to compile.
+        * @param dependencies - The declared names and replacement ranges.
+        * @returns A plan with replaced manifest ranges and a matching hash, or
+        * `undefined` when the manifest or its identity cannot be compiled.
+        *
+        * @remarks
+        * The blueprint remains the workspace specification that produced the plan.
+        * Registry answers alter only the manifest artifact that materialization will
+        * write. Recomputing the hash in the same compiler keeps the plan's identity
+        * tied to those final bytes rather than to the unresolved floor.
+        *
+        * @example
+        * ```ts
+        * import { replacePlanRanges } from '@orkestrel/scaffold'
+        *
+        * replacePlanRanges(plan, releases) // the plan carrying the resolved manifest ranges
+        * ```
+        */
+       export declare function replacePlanRanges(plan: Plan, dependencies: readonly Dependency[]): Plan | undefined;
+
        /**
         * The one error this package throws, carrying the coded reason it was raised.
         *
@@ -2702,7 +2795,7 @@ export declare class Compiler implements CompilerInterface {
         * ```ts
         * import { SHOWCASE_DEV_DEPENDENCIES } from '@orkestrel/scaffold'
         *
-        * SHOWCASE_DEV_DEPENDENCIES['vite-plugin-singlefile'] // '^2.3.3'
+        * SHOWCASE_DEV_DEPENDENCIES['vite-plugin-singlefile'] // the showcase plugin range
         * ```
         */
        export declare const SHOWCASE_DEV_DEPENDENCIES: Readonly<Record<string, string>>;

package/dist/src/core/index.d.ts

@@ -1060,7 +1060,7 @@ export declare class Compiler implements CompilerInterface {
               conformance: "// Where this package drifts from the official tooling it stays compatible with.\n// The subject is this package, so the proof is hermetic and stays in `npm test`.\nexport const conformance = (options?: UserConfig): UserConfig =>\n\tmergeConfig(\n\t\t{\n\t\t\tresolve,\n\t\t\ttest: {\n\t\t\t\tname: { label: 'conformance', color: 'magenta' },\n\t\t\t\tinclude: ['tests/conformance.test.ts'],\n\t\t\t\tsetupFiles: ['./tests/setup.ts'],\n\t\t\t\tenvironment: 'node',\n\t\t\t\tbrowser: { enabled: false },\n\t\t\t},\n\t\t},\n\t\toptions ?? {},\n\t)\n";
               service: "// The live external services this package drives. It starts nothing itself:\n// `scripts/service.sh` provisions, `tests/setupService.ts` proves readiness, and\n// the project stays out of `npm test` because a real service answers it.\nexport const service = (options?: UserConfig): UserConfig =>\n\tmergeConfig(\n\t\t{\n\t\t\tresolve,\n\t\t\ttest: {\n\t\t\t\tname: { label: 'service', color: 'red' },\n\t\t\t\tinclude: ['tests/service/**/*.test.ts'],\n\t\t\t\tsetupFiles: ['./tests/setup.ts', './tests/setupService.ts'],\n\t\t\t\tenvironment: 'node',\n\t\t\t\tbrowser: { enabled: false },\n\t\t\t\ttestTimeout: 120_000,\n\t\t\t\thookTimeout: 120_000,\n\t\t\t\tfileParallelism: false,\n\t\t\t},\n\t\t},\n\t\toptions ?? {},\n\t)\n";
               distribution: "export const distribution = (options?: UserConfig): UserConfig =>\n\tmergeConfig(\n\t\t{\n\t\t\tresolve,\n\t\t\ttest: {\n\t\t\t\tname: { label: 'distribution', color: 'cyan' },\n\t\t\t\tinclude: ['tests/distribution.test.ts'],\n\t\t\t\tsetupFiles: ['./tests/setup.ts'],\n\t\t\t\tenvironment: 'node',\n\t\t\t\ttestTimeout: 120_000,\n\t\t\t\thookTimeout: 120_000,\n\t\t\t\tfileParallelism: false,\n\t\t\t},\n\t\t},\n\t\toptions ?? {},\n\t)\n";
-              probe: "// A workbench, not a proof. No gate selects this project.\nexport const probe = (options?: UserConfig): UserConfig =>\n\tmergeConfig(\n\t\t{\n\t\t\tresolve,\n\t\t\ttest: {\n\t\t\t\tname: { label: 'probe', color: 'gray' },\n\t\t\t\tinclude: ['tmp/probe/**/*.test.ts'],\n\t\t\t\tsetupFiles: ['./tests/setup.ts'],\n\t\t\t\tenvironment: 'node',\n\t\t\t\tbrowser: { enabled: false },\n\t\t\t},\n\t\t},\n\t\toptions ?? {},\n\t)\n";
+              probe: "// A workbench, not a proof. No gate selects this project. Run in test mode by the\n// `test:probe` script, it collects `tmp/probe/**/*.test.ts`. Run in benchmark mode by the\n// `test:bench` script, the same workbench also collects `tests/**/*.test.ts` for a `bench` block,\n// so a suite may carry a bench beside its ordinary tests without a second project. The mode\n// guard around each `bench` call keeps it out of test mode, so it never executes there.\nexport const probe = (options?: UserConfig): UserConfig =>\n\tmergeConfig(\n\t\t{\n\t\t\tresolve,\n\t\t\ttest: {\n\t\t\t\tname: { label: 'probe', color: 'gray' },\n\t\t\t\tinclude: ['tmp/probe/**/*.test.ts'],\n\t\t\t\tsetupFiles: ['./tests/setup.ts'],\n\t\t\t\tenvironment: 'node',\n\t\t\t\tbrowser: { enabled: false },\n\t\t\t\tfileParallelism: false,\n\t\t\t\tpool: 'threads',\n\t\t\t\tbenchmark: { include: ['tmp/probe/**/*.test.ts', 'tests/**/*.test.ts'] },\n\t\t\t},\n\t\t},\n\t\toptions ?? {},\n\t)\n";
               integration: "export const integration = (options?: UserConfig): UserConfig =>\n\tmergeConfig(\n\t\t{\n\t\t\tresolve,\n\t\t\ttest: {\n\t\t\t\tname: { label: 'integration', color: 'blue' },\n\t\t\t\tinclude: ['tests/integration.test.ts'],\n\t\t\t\tsetupFiles: ['./tests/setup.ts'],\n{{global}}\t\t\t\tenvironment: 'node',\n\t\t\t},\n\t\t},\n\t\toptions ?? {},\n\t)\n";
           }>;
           tsconfigs: Readonly<{
@@ -1283,6 +1283,29 @@ export declare class Compiler implements CompilerInterface {
        /** The registry-only semver subset accepted for a development extra's range. */
        export declare const EXTRA_RANGE_PATTERN: RegExp;
 
+       /**
+        * Extract the major component of an admitted dependency range.
+        *
+        * @param range - The candidate range text.
+        * @returns The major number, or `undefined` when the text is not a canonical
+        * major caret or an admitted full-version form.
+        *
+        * @remarks
+        * A canonical toolchain range is `^MAJOR`. Existing consumer declarations may
+        * instead carry an exact `major.minor.patch` version or that version under a
+        * caret or tilde. The projection reads those forms without deciding whether a
+        * version satisfies them; {@link matchesRange} owns that separate question.
+        *
+        * @example
+        * ```ts
+        * import { extractRangeMajor } from '@orkestrel/scaffold'
+        *
+        * extractRangeMajor('^6') // the declared major
+        * extractRangeMajor('>=6.0.0') // undefined
+        * ```
+        */
+       export declare function extractRangeMajor(range: string): number | undefined;
+
        /**
         * Extract the major, minor, and patch components of an exact version.
         *
@@ -2078,9 +2101,29 @@ export declare class Compiler implements CompilerInterface {
        /** Maximum length of one declared package range. */
        export declare const MAX_RANGE_LENGTH = 2048;
 
+       /**
+        * Maximum decoded bytes accepted from one registry response.
+        *
+        * @remarks
+        * The 2026-08-21 abbreviated-packument measurements were 8,647,138 bytes for
+        * TypeScript, 8,077,438 for Playwright, 2,315,360 for `@types/node`, 2,298,256
+        * for Vite, and 1,272,652 for Vitest. The bound leaves headroom above those
+        * registry answers.
+        */
+       export declare const MAX_REGISTRY_BYTES = 33554432;
+
        /** Maximum bytes retained across one whole plan or audit. */
        export declare const MAX_TOTAL_ARTIFACT_BYTES = 104857600;
 
+       /**
+        * Maximum decoded bytes accepted across one registry-reading call.
+        *
+        * @remarks
+        * The 2026-08-21 browser-workspace registry set measured about 24 MiB. The
+        * bound leaves headroom for that set to grow without making a call unbounded.
+        */
+       export declare const MAX_TOTAL_REGISTRY_BYTES = 100663296;
+
        /** The oldest Node version the generated toolchain supports. */
        export declare const MINIMUM_NODE_VERSION = "22.12.0";
 
@@ -2527,30 +2570,80 @@ export declare class Compiler implements CompilerInterface {
        }
 
        /**
-        * One declared dependency range measured against the registry's latest release.
+        * One declared dependency range measured against a registry release.
         *
         * @remarks
-        * A found lookup carries the version upstream reported; one that produced no
-        * answer carries the cause and no version. Whether the declared range already
-        * admits that version is not recorded, because it is a deterministic function
-        * of `range` and `latest`: a stored answer could only disagree with the
-        * fields beside it. One centralized helper decides it, and every caller reads
-        * the same decision.
+        * `range` is the declared range, and `latest` is the version the producer
+        * selected. A found lookup carries that selected version; one that produced no
+        * answer carries the cause and no selected version. `major`, when present, is
+        * the stable major named by the registry's latest tag in the same answer.
         */
        export declare type Release = {
            readonly name: string;
            readonly range: string;
            readonly lookup: 'found';
            readonly latest: string;
+           readonly major?: number;
            readonly note?: never;
        } | {
            readonly name: string;
            readonly range: string;
            readonly lookup: 'missing' | 'failed';
            readonly note: string;
+           readonly major?: number;
            readonly latest?: never;
        };
 
+       /**
+        * Replace declared dependency ranges in package manifest text.
+        *
+        * @param manifest - The manifest text to compile.
+        * @param dependencies - The declared names and replacement ranges.
+        * @returns The manifest with every matching dependency-section value replaced,
+        * or `undefined` when any name has no quoted declaration in those sections.
+        *
+        * @remarks
+        * The compiler replaces values in place instead of serializing the manifest,
+        * so description, keywords, scripts, key order, indentation, and every byte
+        * outside the named ranges survive. Every occurrence in `dependencies`,
+        * `devDependencies`, and `peerDependencies` moves, which keeps duplicate
+        * declarations aligned until the manifest's own validation reports the
+        * duplicate. An override or resolution with the same name stays untouched.
+        *
+        * @example
+        * ```ts
+        * import { replaceManifestRanges } from '@orkestrel/scaffold'
+        *
+        * const manifest = '{"devDependencies":{"typescript":"^6"}}\n'
+        * replaceManifestRanges(manifest, [{ name: 'typescript', range: '^7' }])
+        * // the manifest with the declared range replaced
+        * ```
+        */
+       export declare function replaceManifestRanges(manifest: string, dependencies: readonly Dependency[]): string | undefined;
+
+       /**
+        * Replace dependency ranges in a plan's manifest and recompute its identity.
+        *
+        * @param plan - The plan carrying the manifest artifact to compile.
+        * @param dependencies - The declared names and replacement ranges.
+        * @returns A plan with replaced manifest ranges and a matching hash, or
+        * `undefined` when the manifest or its identity cannot be compiled.
+        *
+        * @remarks
+        * The blueprint remains the workspace specification that produced the plan.
+        * Registry answers alter only the manifest artifact that materialization will
+        * write. Recomputing the hash in the same compiler keeps the plan's identity
+        * tied to those final bytes rather than to the unresolved floor.
+        *
+        * @example
+        * ```ts
+        * import { replacePlanRanges } from '@orkestrel/scaffold'
+        *
+        * replacePlanRanges(plan, releases) // the plan carrying the resolved manifest ranges
+        * ```
+        */
+       export declare function replacePlanRanges(plan: Plan, dependencies: readonly Dependency[]): Plan | undefined;
+
        /**
         * The one error this package throws, carrying the coded reason it was raised.
         *
@@ -2702,7 +2795,7 @@ export declare class Compiler implements CompilerInterface {
         * ```ts
         * import { SHOWCASE_DEV_DEPENDENCIES } from '@orkestrel/scaffold'
         *
-        * SHOWCASE_DEV_DEPENDENCIES['vite-plugin-singlefile'] // '^2.3.3'
+        * SHOWCASE_DEV_DEPENDENCIES['vite-plugin-singlefile'] // the showcase plugin range
         * ```
         */
        export declare const SHOWCASE_DEV_DEPENDENCIES: Readonly<Record<string, string>>;