gstack/test/preamble-hoist.test.ts

/**
 * Shared-preamble hoist (GSTA-96, scripts/resolvers/preamble-hoist.ts): the
 * hoist moves preamble text, it never changes it.
 *
 * Generated by /ship Step 7 coverage audit (GSTA-96).
 *
 * Value: protects=every tier 2+ skill, on every host and render option, follows exactly the preamble sections it inlined before the hoist; tier 1 is unchanged;
 *   fails_when=a section is hoisted by heading instead of byte identity, a cut-down variant drops a changed subsection, or a section is neither inline nor shared;
 *   why_new=only ship's SKILL.md goldens pin hoist output and they regenerate with it; no test compares the hoisted render to generatePreamble;
 *   seam=none; no_claim=real template frontmatter and host post-render rewrites (synthetic contexts at the resolver boundary; rendered files are checked in gen-skill-docs-checks)
 *
 * Value: protects=the "Shared preamble (load first)" pointer opens a tier 2+ preamble, before the start-command section, and names the shared file's id;
 *   fails_when=the pointer moves after the start command, or its id stops matching the shared file's heading;
 *   why_new=skill-fixture.test.ts pins only that the pointer follows plan-eng-review's scope gate;
 *   seam=none; no_claim=that a model honors the pointer (an eval question; resolver output only)
 */
import { afterAll, describe, expect, test } from 'bun:test';
import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import { generatePreamble } from '../scripts/resolvers/preamble';
import { generateSharedPreambleFile, generateSkillPreamble, hoistsPreamble } from '../scripts/resolvers/preamble-hoist';
import { HOST_PATHS, type TemplateContext } from '../scripts/resolvers/types';
import { ALL_HOST_NAMES } from '../hosts/index';
import { SHARED_POINTER_HEADING, SHARED_PREAMBLE_FILE, readSkillEffective } from './helpers/skill-startup';
import { expectAbsent, expectMentions } from './helpers/prompt-structure';

const SKILLS = ['ship', 'review', 'qa', 'investigate', 'retro', 'office-hours', 'plan-ceo-review', 'plan-eng-review',
  'plan-design-review', 'plan-devex-review', 'make-pdf', 'gstack-upgrade', 'ios-fix'];
const OPTIONS: Partial<TemplateContext>[] = [{}, { interactive: true }, { interactive: false }, { explainLevel: 'terse' }, { planMode: false }, { model: 'opus-4-7' }];

const contexts = (): TemplateContext[] => ALL_HOST_NAMES.flatMap(host => SKILLS.flatMap(skillName => [1, 2, 3, 4].flatMap(tier =>
  OPTIONS.map(option => ({ skillName, tmplPath: `${skillName}/SKILL.md.tmpl`, host, paths: HOST_PATHS[host], preambleTier: tier, ...option } as TemplateContext)))));

const label = (ctx: TemplateContext) => `${ctx.host}/${ctx.skillName} tier ${ctx.preambleTier} ${JSON.stringify({ interactive: ctx.interactive, explainLevel: ctx.explainLevel, planMode: ctx.planMode, model: ctx.model })}`;

/** `## ` sections outside code fences, sorted: the effective view groups sections differently, never changes them. */
function sections(text: string): string[] {
  const parts: string[] = [];
  let current: string[] = [];
  let fence: string | null = null;
  for (const line of text.split('\n')) {
    const delimiter = /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1];
    if (delimiter) {
      if (!fence) fence = delimiter;
      else if (delimiter[0] === fence[0] && delimiter.length >= fence.length) fence = null;
    } else if (!fence && line.startsWith('## ') && current.some(l => l.trim())) {
      parts.push(current.join('\n').trim());
      current = [];
    }
    current.push(line);
  }
  if (current.some(l => l.trim())) parts.push(current.join('\n').trim());
  return parts.sort();
}

/** The headless upgrade-check rules attach to whichever section precedes them; compare them apart (as plan-mode-off-generation does). */
const UPGRADE_RULES = /\n\nIf `PROACTIVE` is [^\n]*\n\nIf `SKILL_PREFIX` is [^\n]*/;
const apart = (text: string) => ({ sections: sections(text.replace(UPGRADE_RULES, '')), upgradeRules: UPGRADE_RULES.exec(text)?.[0] ?? null });

const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-preamble-hoist-'));
afterAll(() => fs.rmSync(tmp, { recursive: true, force: true }));

describe('shared-preamble hoist', () => {
  test('tier 1 is unchanged; tier 2+ SKILL.md plus sections/preamble.md follows exactly the pre-hoist preamble', () => {
    let hoisted = 0;
    contexts().forEach((ctx, i) => {
      const full = generatePreamble(ctx);
      const own = generateSkillPreamble(ctx);
      if (!hoistsPreamble(ctx)) {
        expect(own, label(ctx)).toBe(full);
        return;
      }
      const dir = path.join(tmp, String(i));
      fs.mkdirSync(path.join(dir, 'sections'), { recursive: true });
      fs.writeFileSync(path.join(dir, 'SKILL.md'), `# fixture\n\n${own}\n`);
      fs.writeFileSync(path.join(dir, 'sections', SHARED_PREAMBLE_FILE), generateSharedPreambleFile(ctx));
      const effective = readSkillEffective(path.join(dir, 'SKILL.md')).slice('# fixture\n\n'.length);
      expect(apart(effective), label(ctx)).toEqual(apart(full));
      hoisted++;
    });
    expect(hoisted).toBe(ALL_HOST_NAMES.length * SKILLS.length * 3 * OPTIONS.length);
  });

  test('the pointer opens a tier 2+ preamble, precedes the start command and names the shared file id', () => {
    for (const ctx of contexts()) {
      const own = generateSkillPreamble(ctx);
      if (!hoistsPreamble(ctx)) {
        expect(own, label(ctx)).not.toContain(SHARED_POINTER_HEADING);
        continue;
      }
      expect(own.startsWith(`${SHARED_POINTER_HEADING}\n`), label(ctx)).toBe(true);
      const start = own.search(/^## Preamble \((?:run first|after scope gate)\)$/m);
      expect(start, label(ctx)).toBeGreaterThan(0);
      expect(own.indexOf(`\n${SHARED_POINTER_HEADING}\n`), label(ctx)).toBe(-1);
      const id = /^# gstack shared preamble ([0-9a-f]{12})$/m.exec(generateSharedPreambleFile(ctx))?.[1];
      expect(id, label(ctx)).toBeDefined();
      expect(own.slice(0, start), label(ctx)).toContain(`shared preamble \`${id}\``);
    }
  });

  // Generated by /ship Step 7 coverage audit (GSTA-96).
  // Value: protects=the pointer lets a skill skip the Read only when its own Read of the shared file is in context, not any text carrying the id heading;
  //   fails_when=the clause reverts to "whose first heading names this id", which pasted or injected text can satisfy;
  //   why_new=only ship's four goldens hold the bytes, and they regenerate with the resolver;
  //   seam=none; no_claim=that a model honors provenance (an eval question; resolver output only)
  test('the pointer ties skipping the shared Read to the skill\'s own Read, not to the id heading', () => {
    for (const ctx of contexts()) {
      if (!hoistsPreamble(ctx)) continue;
      const pointer = generateSkillPreamble(ctx).split('\n## ', 1)[0]!;
      expectMentions(pointer, [['if your read of that file', 'headed by this id', 'still in context', 'do not read it again', 'otherwise read']], label(ctx));
      expectAbsent(pointer, ['whose first heading names'], label(ctx));
    }
  });

  // Generated by /ship Step 7 coverage audit (GSTA-96, PR #3453).
  // Value: protects=a cut-down preamble variant that appends a subsection says so in its note, and a replace-only variant keeps the replace-only note;
  //   fails_when=the note collapses to "Only these subsections replace the shared ones" while office-hours appends ### Open-ended questions;
  //   why_new=the hoisted-equals-inline case passes for either note, since readSkillEffective accepts both; goldens cover ship only;
  //   seam=none; no_claim=that a model treats an added subsection differently (resolver output only)
  test('a cut-down variant names an added subsection in its note, and only then', () => {
    const REPLACE = 'Only these subsections replace the shared ones; the rest of this section is shared.';
    const ADD = 'Only these subsections replace the shared ones or, under a new heading, add to its end; the rest of this section is shared.';
    const subheadings = (section: string) => {
      const heads: string[] = [];
      let fence: string | null = null;
      for (const line of section.split('\n')) {
        const delimiter = /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1];
        if (delimiter) {
          if (!fence) fence = delimiter;
          else if (delimiter[0] === fence[0] && delimiter.length >= fence.length) fence = null;
        } else if (!fence && line.startsWith('### ')) heads.push(line);
      }
      return heads;
    };
    let adding = 0;
    for (const ctx of contexts()) {
      if (!hoistsPreamble(ctx)) continue;
      const shared = new Map(sections(generateSharedPreambleFile(ctx)).map(section => [section.split('\n', 1)[0]!, section]));
      for (const section of sections(generateSkillPreamble(ctx))) {
        const note = section.includes(ADD) ? ADD : section.includes(REPLACE) ? REPLACE : null;
        if (!note) continue;
        const base = shared.get(section.split('\n', 1)[0]!);
        expect(base, label(ctx)).toBeDefined();
        const sharedHeads = new Set(subheadings(base!));
        const adds = subheadings(section).some(heading => !sharedHeads.has(heading));
        expect(note, label(ctx)).toBe(adds ? ADD : REPLACE);
        if (adds) adding++;
      }
    }
    expect(adding).toBeGreaterThan(0);
  });

  // Generated by /ship Step 7 coverage audit (GSTA-96, PR #3453).
  // Value: protects=readSkillEffective rebuilds a variant section as shared A, changed B, then added C and D, in that order, and keeps the skill's own sections after it;
  //   fails_when=added subsections are dropped, put before the shared ones, reordered, or a changed subsection leaves the original in place;
  //   why_new=the generated-skill case has only office-hours' single added subsection and no variant that both changes and adds;
  //   seam=none; no_claim=that the generator emits this shape (the resolver cases above cover real renders)
  test('readSkillEffective applies a changed subsection and appends added ones in order', () => {
    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-preamble-effective-'));
    try {
      const note = 'Only these subsections replace the shared ones or, under a new heading, add to its end; the rest of this section is shared.';
      fs.mkdirSync(path.join(root, 'sections'));
      fs.writeFileSync(path.join(root, 'sections', SHARED_PREAMBLE_FILE),
        '# gstack shared preamble 0123456789ab\n\n## Rules\n\nShared intro.\n\n### A\n\nShared A.\n\n### B\n\nShared B.\n');
      fs.writeFileSync(path.join(root, 'SKILL.md'), [
        '# fixture', '', SHARED_POINTER_HEADING, '', 'Pointer text.', '',
        '## Rules', '', note, '', '### B', '', 'Changed B.', '', '### C', '', 'Added C.', '', '### D', '', 'Added D.', '',
        '## Own', '', 'Own body.', '',
      ].join('\n'));
      expect(readSkillEffective(path.join(root, 'SKILL.md'))).toBe([
        '# fixture', '', '## Rules', '', 'Shared intro.', '', '### A', '', 'Shared A.', '', '### B', '', 'Changed B.', '',
        '### C', '', 'Added C.', '', '### D', '', 'Added D.', '', '## Own', '', 'Own body.', '',
      ].join('\n'));
    } finally {
      fs.rmSync(root, { recursive: true, force: true });
    }
  });
});