@ramplab/generator 0.1.0

package/dist/flagship.js

@@ -0,0 +1,216 @@
+import { hasIntakeAnswers } from './intake.js';
+import { LANDING_MODULE_ID, plannedModuleSchema, } from './planStage.js';
+/** Raised when the map offers nothing teachable to author. */
+export class FlagshipSelectionError extends Error {
+    constructor(message) {
+        super(`Flagship selection failed: ${message}`);
+        this.name = 'FlagshipSelectionError';
+    }
+}
+export function selectFlagshipModule(mapSpec, intake, traceCandidates) {
+    const fromTrace = selectTraceFlagship(traceCandidates, intake);
+    if (fromTrace !== undefined)
+        return fromTrace;
+    return selectCentralityFlagship(mapSpec, intake);
+}
+// ---------------------------------------------------------------------------
+// Trace-based selection (the primary path)
+// ---------------------------------------------------------------------------
+/**
+ * Select the flagship trace from the map's candidate actions, or `undefined`
+ * when there are no candidates (callers fall back to centrality). Exported
+ * separately because pass 2 uses it too: the plan stage pins its module 1 to
+ * the same selection pass 1 previewed.
+ */
+export function selectTraceFlagship(traceCandidates, intake) {
+    if (traceCandidates === undefined || traceCandidates.length === 0)
+        return undefined;
+    const searchable = traceCandidates.map((candidate) => ({
+        candidate,
+        searchText: [
+            candidate.id,
+            candidate.action,
+            candidate.description ?? '',
+            ...candidate.keyFiles,
+        ]
+            .join(' ')
+            .toLowerCase(),
+    }));
+    const fromIntake = matchIntakeHints(searchable, intake);
+    if (fromIntake !== undefined) {
+        return toTraceSelection(fromIntake.matched.candidate, 'trace-intake', intake, fromIntake.hint);
+    }
+    // Map order is the representativeness ranking (see the map prompt).
+    const first = traceCandidates[0];
+    return toTraceSelection(first, 'trace', intake);
+}
+/**
+ * Ids owned by other parts of the pipeline: the map stage's overview module
+ * and the plan stage's mandated landing module. A colliding candidate id is
+ * suffixed rather than rejected.
+ */
+function traceModuleId(candidateId) {
+    return candidateId === 'repo-overview' || candidateId === LANDING_MODULE_ID
+        ? `${candidateId}-trace`
+        : candidateId;
+}
+function toTraceSelection(candidate, basis, intake, matchedHint) {
+    const focusParts = [
+        `This module is the lab's opening trace: follow ONE real user action end to ` +
+            `end through the code. The action: ${candidate.action}.`,
+    ];
+    if (candidate.description !== undefined) {
+        focusParts.push(candidate.description);
+    }
+    focusParts.push(`Start at the entry point and walk the exact path the action takes — file by ` +
+        `file, layer by layer — teaching each mechanism concretely as the action ` +
+        `reaches it, before naming any abstraction it exemplifies.`, `Widget order is part of the pedagogy: the module MUST open with a ` +
+        `code-walkthrough stepping through this action's entry point — the learner's ` +
+        `first contact is real code being walked, never a diagram. A system-map of ` +
+        `the path may appear only after the walkthroughs, as a recap of ground ` +
+        `already covered.`, basis === 'trace-intake'
+        ? `The onboarding lead's intake singled this area out ("${matchedHint ?? ''}").`
+        : `The map stage judged this the most representative front-door action of this codebase.`);
+    const intakeLine = renderIntakeFocusLine(intake);
+    if (intakeLine !== undefined)
+        focusParts.push(intakeLine);
+    const plannedModule = plannedModuleSchema.parse({
+        id: traceModuleId(candidate.id),
+        title: `End to end: ${candidate.action}`,
+        focus: focusParts.join(' '),
+        keyFiles: candidate.keyFiles,
+        assumes: [],
+        teaches: [
+            `how "${candidate.action}" flows end to end through this codebase`,
+            'the files and layers along that path, and why each exists',
+        ],
+    });
+    return {
+        basis,
+        traceAction: candidate.action,
+        ...(matchedHint !== undefined ? { matchedHint } : {}),
+        plannedModule,
+    };
+}
+function selectCentralityFlagship(mapSpec, intake) {
+    const systemMap = findSystemMap(mapSpec);
+    if (systemMap === undefined) {
+        throw new FlagshipSelectionError('the map spec contains no system-map widget.');
+    }
+    const candidates = systemMap.nodes
+        .map((node) => toNodeCandidate(node, systemMap.edges))
+        .filter((candidate) => candidate.keyFiles.length > 0);
+    if (candidates.length === 0) {
+        throw new FlagshipSelectionError('no system-map node carries an anchor (directly or via an incident edge), ' +
+            'so there are no key files to author from.');
+    }
+    const fromIntake = matchIntakeHints(candidates, intake);
+    if (fromIntake !== undefined) {
+        return toNodeSelection(fromIntake.matched, 'intake', intake, fromIntake.hint);
+    }
+    let best = candidates[0];
+    for (const candidate of candidates) {
+        if (candidate.degree > best.degree)
+            best = candidate; // ties keep map order
+    }
+    return toNodeSelection(best, 'centrality', intake);
+}
+function findSystemMap(mapSpec) {
+    for (const module of mapSpec.base.modules) {
+        for (const widget of module.widgets) {
+            if (widget.type === 'system-map')
+                return widget;
+        }
+    }
+    return undefined;
+}
+function toNodeCandidate(node, edges) {
+    const incident = edges.filter((edge) => edge.from === node.id || edge.to === node.id);
+    const keyFiles = [
+        ...new Set([...(node.anchors ?? []), ...incident.flatMap((edge) => edge.anchors ?? [])].map((anchor) => anchor.file)),
+    ];
+    const searchText = [node.id, node.label, node.description ?? '', ...keyFiles]
+        .join(' ')
+        .toLowerCase();
+    return { node, degree: incident.length, keyFiles, searchText };
+}
+/** The map stage owns `repo-overview`; a colliding node id gets suffixed. */
+function flagshipModuleId(nodeId) {
+    return nodeId === 'repo-overview' ? 'repo-overview-flagship' : nodeId;
+}
+function toNodeSelection(candidate, basis, intake, matchedHint) {
+    const { node, degree, keyFiles } = candidate;
+    const focusParts = [
+        `Teach "${node.label}" as this repository's flagship subsystem — the single ` +
+            `deepest first look a new engineer gets.`,
+    ];
+    if (node.description !== undefined) {
+        focusParts.push(node.description);
+    }
+    focusParts.push(basis === 'intake'
+        ? `The onboarding lead's intake singled this area out ("${matchedHint ?? ''}").`
+        : `It was chosen by subsystem centrality: ${degree} edge${degree === 1 ? '' : 's'} ` +
+            `of the system map touch it.`);
+    const intakeLine = renderIntakeFocusLine(intake);
+    if (intakeLine !== undefined)
+        focusParts.push(intakeLine);
+    const plannedModule = plannedModuleSchema.parse({
+        id: flagshipModuleId(node.id),
+        title: node.label,
+        focus: focusParts.join(' '),
+        keyFiles,
+        assumes: [],
+        teaches: [`how the "${node.label}" subsystem works and its role in the system`],
+    });
+    return {
+        basis,
+        nodeId: node.id,
+        degree,
+        ...(matchedHint !== undefined ? { matchedHint } : {}),
+        plannedModule,
+    };
+}
+// ---------------------------------------------------------------------------
+// Shared intake-hint matching
+// ---------------------------------------------------------------------------
+/**
+ * A hint matches an item when any of its words (4+ characters, so "the"/"a"
+ * never match) appears in the item's search text. Hints are scanned in
+ * intake priority order; items in map order.
+ */
+function matchIntakeHints(items, intake) {
+    if (!hasIntakeAnswers(intake))
+        return undefined;
+    const hints = [...(intake.weekOneMastery ?? []), ...(intake.activeDevelopment ?? [])];
+    for (const hint of hints) {
+        const words = hint
+            .toLowerCase()
+            .split(/[^a-z0-9]+/)
+            .filter((word) => word.length >= 4);
+        if (words.length === 0)
+            continue;
+        for (const matched of items) {
+            if (words.some((word) => matched.searchText.includes(word))) {
+                return { matched, hint };
+            }
+        }
+    }
+    return undefined;
+}
+/** The intake summary appended to every flagship brief, when present. */
+function renderIntakeFocusLine(intake) {
+    if (!hasIntakeAnswers(intake))
+        return undefined;
+    const inline = [];
+    if ((intake.weekOneMastery?.length ?? 0) > 0) {
+        inline.push(`week-one hires must master: ${intake.weekOneMastery.join('; ')}`);
+    }
+    if ((intake.activeDevelopment?.length ?? 0) > 0) {
+        inline.push(`under active development: ${intake.activeDevelopment.join('; ')}`);
+    }
+    if ((intake.gotchas?.length ?? 0) > 0) {
+        inline.push(`known gotchas to call out: ${intake.gotchas.join('; ')}`);
+    }
+    return `Lead intake — ${inline.join('. ')}.`;
+}
+//# sourceMappingURL=flagship.js.map

package/dist/flagship.js.map

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

package/dist/generateLab.d.ts

@@ -0,0 +1,151 @@
+import type { LabSpec } from '@ramplab/spec';
+import type { LeadIntake } from './intake.js';
+import { type MapStageResult } from './mapStage.js';
+import { type GenerationStageName, type ModelRunner, type StageModelConfig } from './pipeline.js';
+import { type CurriculumBudget, type CurriculumPlan, type PlannedModule } from './planStage.js';
+import type { ProgressCallback } from './progress.js';
+import { type ResolutionPolicy, type ResolutionReport } from './resolveAnchors.js';
+import { type VerificationReport } from './verifyStage.js';
+/**
+ * `generateLab(repoDir, config)` — the generator entry point (PLAN.md §4).
+ *
+ * Two modes on the same config/runner plumbing:
+ *
+ * - **Tracer (default, `full` unset/false):** the map stage only — agent
+ *   explores the repo (read-only), emits a system-map widget plus one module
+ *   of anchored callouts. Predates the two-pass runtime; for the streamed
+ *   pass-1 preview (map + flagship module) use `generateLabPass1` in
+ *   `pass1.ts`. The tracer emits no progress events.
+ * - **Full pipeline (`full: true`) — pass 2 of the two-pass runtime:**
+ *   map → curriculum plan → author (parallel per planned module,
+ *   concurrency-capped) → assemble → verify. The plan stage plans a
+ *   dependency-ordered journey (issue #18) within `config.budget` (a config
+ *   cap, never repo size), steered by the lead's `config.intake` answers
+ *   when present: module 1 is pinned to the flagship trace when the map
+ *   proposed candidates, every module carries an `assumes`/`teaches`
+ *   learner-state ledger, and the final module is always "your first
+ *   contribution". Each planned module is authored by its own agent call
+ *   (with its ledger slice and the style contract in the prompt); assembly
+ *   merges everything into one spec, revalidates, and runs anchor resolution
+ *   per policy; the verify stage then adversarially checks every surviving
+ *   claim against its anchored code and drops what it cannot verify
+ *   (PLAN.md §3).
+ *
+ * **Map reuse (`config.mapResult`):** pass 2 normally runs right after pass 1
+ * on the same repo snapshot, so callers hand pass 1's `mapResult` in and the
+ * map stage is skipped entirely — no second map agent call. The reused map's
+ * cost is NOT re-counted in this run's `costUsd` (it was paid in pass 1).
+ * The pass-1 **flagship module is deliberately re-authored, not reused**:
+ * the plan stage owns pass 2's curriculum (ids, ordering, briefs), and
+ * splicing a module authored against pass 1's ad-hoc brief into it would
+ * make the draft's shape depend on which pass wrote which module. Pass 1 is
+ * a preview; pass 2 is the canonical draft.
+ *
+ * **Progress (`config.onProgress`):** full-pipeline runs emit typed events
+ * (see `progress.ts`) tagged `pass: 'pass2'` — stage boundaries,
+ * per-module authoring, and `spec-updated` snapshots that are always valid
+ * and anchor-resolved, so a caller can render each one as it lands.
+ *
+ * Zero infra assumptions: the input is a plain local directory. No cloning,
+ * no network beyond the model API (and none at all with an injected fake
+ * runner).
+ */
+export interface GenerateLabConfig {
+    /**
+     * Run the full pipeline (map → plan → author → assemble → verify) instead
+     * of the map-only tracer.
+     * @default false
+     */
+    full?: boolean;
+    /**
+     * Per-stage model map. Every stage defaults to `claude-sonnet-5`;
+     * overrides are honored per stage (PLAN.md §10).
+     */
+    models?: StageModelConfig;
+    /**
+     * Curriculum budget for the plan stage (full pipeline only): max module
+     * count and scope hints. Caps lab scope by config, not repo size.
+     */
+    budget?: CurriculumBudget;
+    /**
+     * The lead's 2-minute intake (PLAN.md §4 curation loop). Threaded into the
+     * curriculum-plan prompt so the answers steer module selection/ordering,
+     * and into pass 1's flagship choice (see `flagship.ts`).
+     */
+    intake?: LeadIntake;
+    /**
+     * Progress-event callback — the streaming seam (see `progress.ts`).
+     * Full-pipeline runs emit `pass: 'pass2'` events; the tracer emits none.
+     */
+    onProgress?: ProgressCallback;
+    /**
+     * A previous map-stage result (typically pass 1's `result.mapResult`).
+     * When present, the map stage is skipped and this output is used verbatim;
+     * its cost is not re-counted. Full pipeline only.
+     */
+    mapResult?: MapStageResult;
+    /**
+     * Millisecond clock for timing measurements, injectable for tests.
+     * Only the live path should rely on the `Date.now` default.
+     * @default Date.now
+     */
+    clock?: () => number;
+    /**
+     * Max authoring agents in flight at once (full pipeline only).
+     * @default 4
+     */
+    concurrency?: number;
+    /**
+     * What to do with teachable units whose anchors fail to resolve:
+     * `drop` (default) removes them; `flag` keeps them and only reports.
+     */
+    resolutionPolicy?: ResolutionPolicy;
+    /**
+     * The agent-invocation boundary. Defaults to the real Claude Agent SDK
+     * runner; tests inject a fake so CI never makes live API calls.
+     */
+    runner?: ModelRunner;
+    /**
+     * Bounded retries per stage (and per authored module) when the model's
+     * output is schema-invalid.
+     * @default 1
+     */
+    maxRetries?: number;
+    /** Lab id override; defaults to a slug of the repo directory name. */
+    labId?: string;
+}
+export interface GenerateLabResult {
+    /** The validated, anchor-resolved lab spec. */
+    spec: LabSpec;
+    /** Full anchor-resolution report (what resolved, dropped, or flagged). */
+    resolution: ResolutionReport;
+    /** The fully-resolved per-stage model map used for this run. */
+    models: Record<GenerationStageName, string>;
+    /** Total model cost in USD across all stages, when the runner reports cost. */
+    costUsd: number | undefined;
+    /** Map-stage attempts (1 = first output was already valid). */
+    attempts: number;
+    /** The curriculum plan, present only on full-pipeline runs. */
+    plan?: CurriculumPlan;
+    /** Per-module authoring attempts, present only on full-pipeline runs. */
+    authorAttempts?: Record<string, number>;
+    /**
+     * Adversarial verification report (per-claim verdicts, pass rate, drops),
+     * present only on full-pipeline runs.
+     */
+    verification?: VerificationReport;
+    /** Per-module verifier attempts, present only on full-pipeline runs. */
+    verifyAttempts?: Record<string, number>;
+}
+export declare function generateLab(repoDir: string, config?: GenerateLabConfig): Promise<GenerateLabResult>;
+/** The map stage's zoom-out chapter — a stable id learner progress keys off. */
+export declare const OVERVIEW_MODULE_ID = "repo-overview";
+/**
+ * Build the planned-module brief for the zoom-out chapter: what the reader
+ * already walked (the flagship trace's `teaches`), and what this chapter owes
+ * them. Exported for tests — the brief IS the fix, so it is worth pinning.
+ */
+export declare function plannedOverviewModule(mapSpec: LabSpec, plan: CurriculumPlan): PlannedModule | undefined;
+export declare function sumCosts(...costs: (number | undefined)[]): number | undefined;
+export declare function assertDirectory(repoDir: string): void;
+//# sourceMappingURL=generateLab.d.ts.map

package/dist/generateLab.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateLab.d.ts","sourceRoot":"","sources":["../src/generateLab.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAK7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAe,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;;OAGG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,IAAI,EAAE,OAAO,CAAC;IACd,0EAA0E;IAC1E,UAAU,EAAE,gBAAgB,CAAC;IAC7B,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC;IAC5C,+EAA+E;IAC/E,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC;;;OAGG;IACH,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAED,wBAAsB,WAAW,CAC/B,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,iBAAsB,GAC7B,OAAO,CAAC,iBAAiB,CAAC,CAsM5B;AAED,gFAAgF;AAChF,eAAO,MAAM,kBAAkB,kBAAkB,CAAC;AAkBlD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,cAAc,GACnB,aAAa,GAAG,SAAS,CAkC3B;AAyDD,wBAAgB,QAAQ,CAAC,GAAG,KAAK,EAAE,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,GAAG,MAAM,GAAG,SAAS,CAQ7E;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAUrD"}