@popoverai/dotrequirements 0.23.0 → 0.24.0

package/dist/codebase-to-spec/schemas.d.ts

@@ -0,0 +1,257 @@
+/**
+ * JSON schemas for outline + reviewer output.
+ *
+ * The CLI passes these to `claude -p --json-schema` to constrain agent output,
+ * then validates the parsed result before driving the loop.
+ *
+ * Requirements covered:
+ * - CTS-PLAN-1: outline structure
+ * - CTS-PLAN-2: outline reviewer output structure (categorized findings + verdict)
+ */
+import { z } from "zod";
+export declare const AreaSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    prefix: z.ZodString;
+    files: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    prefix: string;
+    files: string[];
+    name: string;
+    description: string;
+}, {
+    prefix: string;
+    files: string[];
+    name: string;
+    description: string;
+}>;
+export type Area = z.infer<typeof AreaSchema>;
+export declare const OutlineSchema: z.ZodObject<{
+    title: z.ZodString;
+    defaultPrefix: z.ZodString;
+    summary: z.ZodString;
+    areas: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        prefix: z.ZodString;
+        files: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        prefix: string;
+        files: string[];
+        name: string;
+        description: string;
+    }, {
+        prefix: string;
+        files: string[];
+        name: string;
+        description: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    defaultPrefix: string;
+    summary: string;
+    areas: {
+        prefix: string;
+        files: string[];
+        name: string;
+        description: string;
+    }[];
+}, {
+    title: string;
+    defaultPrefix: string;
+    summary: string;
+    areas: {
+        prefix: string;
+        files: string[];
+        name: string;
+        description: string;
+    }[];
+}>;
+export type Outline = z.infer<typeof OutlineSchema>;
+/**
+ * JSON Schema for the outline, passed to `claude -p --json-schema`.
+ * Mirrors OutlineSchema in JSON Schema form (which `claude -p` accepts).
+ */
+export declare const OUTLINE_JSON_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly title: {
+            readonly type: "string";
+        };
+        readonly defaultPrefix: {
+            readonly type: "string";
+        };
+        readonly summary: {
+            readonly type: "string";
+        };
+        readonly areas: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly name: {
+                        readonly type: "string";
+                    };
+                    readonly description: {
+                        readonly type: "string";
+                    };
+                    readonly prefix: {
+                        readonly type: "string";
+                    };
+                    readonly files: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+                readonly required: readonly ["name", "description", "prefix", "files"];
+                readonly additionalProperties: false;
+            };
+        };
+    };
+    readonly required: readonly ["title", "defaultPrefix", "summary", "areas"];
+    readonly additionalProperties: false;
+};
+export declare const VerdictValues: readonly ["approved", "approved-with-revisions", "requires-another-review"];
+export type Verdict = (typeof VerdictValues)[number];
+export declare const OutlineReviewSchema: z.ZodObject<{
+    coverage_gaps: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    framing_errors: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    granularity_issues: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    file_assignment_issues: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    revisions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    verdict: z.ZodEnum<["approved", "approved-with-revisions", "requires-another-review"]>;
+}, "strip", z.ZodTypeAny, {
+    coverage_gaps: string[];
+    framing_errors: string[];
+    granularity_issues: string[];
+    file_assignment_issues: string[];
+    revisions: string[];
+    verdict: "approved" | "approved-with-revisions" | "requires-another-review";
+}, {
+    verdict: "approved" | "approved-with-revisions" | "requires-another-review";
+    coverage_gaps?: string[] | undefined;
+    framing_errors?: string[] | undefined;
+    granularity_issues?: string[] | undefined;
+    file_assignment_issues?: string[] | undefined;
+    revisions?: string[] | undefined;
+}>;
+export type OutlineReview = z.infer<typeof OutlineReviewSchema>;
+export declare const OUTLINE_REVIEW_JSON_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly coverage_gaps: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly framing_errors: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly granularity_issues: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly file_assignment_issues: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly revisions: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly verdict: {
+            readonly type: "string";
+            readonly enum: readonly string[];
+        };
+    };
+    readonly required: readonly ["coverage_gaps", "framing_errors", "granularity_issues", "file_assignment_issues", "revisions", "verdict"];
+    readonly additionalProperties: false;
+};
+/**
+ * Try to parse a string as JSON and validate against the outline schema.
+ * Throws with a descriptive message on failure (caller catches and either
+ * retries or fails the loop).
+ */
+export declare function parseOutline(text: string): Outline;
+/**
+ * Parse a reviewer's JSON output and validate against the outline-review schema.
+ */
+export declare function parseOutlineReview(text: string): OutlineReview;
+export declare const SpecReviewSchema: z.ZodObject<{
+    coverage_gaps: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    framing_errors: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    cross_area_issues: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    internal_mechanics_drift: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    revisions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    verdict: z.ZodEnum<["approved", "approved-with-revisions", "requires-another-review"]>;
+}, "strip", z.ZodTypeAny, {
+    coverage_gaps: string[];
+    framing_errors: string[];
+    revisions: string[];
+    verdict: "approved" | "approved-with-revisions" | "requires-another-review";
+    cross_area_issues: string[];
+    internal_mechanics_drift: string[];
+}, {
+    verdict: "approved" | "approved-with-revisions" | "requires-another-review";
+    coverage_gaps?: string[] | undefined;
+    framing_errors?: string[] | undefined;
+    revisions?: string[] | undefined;
+    cross_area_issues?: string[] | undefined;
+    internal_mechanics_drift?: string[] | undefined;
+}>;
+export type SpecReview = z.infer<typeof SpecReviewSchema>;
+export declare const SPEC_REVIEW_JSON_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly coverage_gaps: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly framing_errors: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly cross_area_issues: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly internal_mechanics_drift: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly revisions: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly verdict: {
+            readonly type: "string";
+            readonly enum: readonly string[];
+        };
+    };
+    readonly required: readonly ["coverage_gaps", "framing_errors", "cross_area_issues", "internal_mechanics_drift", "revisions", "verdict"];
+    readonly additionalProperties: false;
+};
+export declare function parseSpecReview(text: string): SpecReview;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/codebase-to-spec/schemas.js

@@ -0,0 +1,183 @@
+/**
+ * JSON schemas for outline + reviewer output.
+ *
+ * The CLI passes these to `claude -p --json-schema` to constrain agent output,
+ * then validates the parsed result before driving the loop.
+ *
+ * Requirements covered:
+ * - CTS-PLAN-1: outline structure
+ * - CTS-PLAN-2: outline reviewer output structure (categorized findings + verdict)
+ */
+import { z } from "zod";
+// ---------- Outline ----------
+export const AreaSchema = z.object({
+    name: z.string().min(1),
+    description: z.string().min(1),
+    prefix: z
+        .string()
+        .regex(/^[A-Z][A-Z0-9_]*$/, "prefix must be uppercase alphanumeric/underscore"),
+    files: z.array(z.string()).min(0),
+});
+export const OutlineSchema = z.object({
+    title: z.string().min(1),
+    defaultPrefix: z
+        .string()
+        .regex(/^[A-Z][A-Z0-9_]*$/, "defaultPrefix must be uppercase alphanumeric/underscore"),
+    summary: z.string().min(1),
+    areas: z.array(AreaSchema).min(1),
+});
+/**
+ * JSON Schema for the outline, passed to `claude -p --json-schema`.
+ * Mirrors OutlineSchema in JSON Schema form (which `claude -p` accepts).
+ */
+export const OUTLINE_JSON_SCHEMA = {
+    type: "object",
+    properties: {
+        title: { type: "string" },
+        defaultPrefix: { type: "string" },
+        summary: { type: "string" },
+        areas: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    name: { type: "string" },
+                    description: { type: "string" },
+                    prefix: { type: "string" },
+                    files: { type: "array", items: { type: "string" } },
+                },
+                required: ["name", "description", "prefix", "files"],
+                additionalProperties: false,
+            },
+        },
+    },
+    required: ["title", "defaultPrefix", "summary", "areas"],
+    additionalProperties: false,
+};
+// ---------- Outline review verdict ----------
+export const VerdictValues = [
+    "approved",
+    "approved-with-revisions",
+    "requires-another-review",
+];
+export const OutlineReviewSchema = z.object({
+    coverage_gaps: z.array(z.string()).default([]),
+    framing_errors: z.array(z.string()).default([]),
+    granularity_issues: z.array(z.string()).default([]),
+    file_assignment_issues: z.array(z.string()).default([]),
+    revisions: z.array(z.string()).default([]),
+    verdict: z.enum(VerdictValues),
+});
+export const OUTLINE_REVIEW_JSON_SCHEMA = {
+    type: "object",
+    properties: {
+        coverage_gaps: { type: "array", items: { type: "string" } },
+        framing_errors: { type: "array", items: { type: "string" } },
+        granularity_issues: { type: "array", items: { type: "string" } },
+        file_assignment_issues: { type: "array", items: { type: "string" } },
+        revisions: { type: "array", items: { type: "string" } },
+        verdict: {
+            type: "string",
+            enum: VerdictValues,
+        },
+    },
+    required: [
+        "coverage_gaps",
+        "framing_errors",
+        "granularity_issues",
+        "file_assignment_issues",
+        "revisions",
+        "verdict",
+    ],
+    additionalProperties: false,
+};
+/**
+ * Try to parse a string as JSON and validate against the outline schema.
+ * Throws with a descriptive message on failure (caller catches and either
+ * retries or fails the loop).
+ */
+export function parseOutline(text) {
+    const trimmed = text.trim();
+    // Try direct parse first; fall back to extracting first {...} block.
+    let raw;
+    try {
+        raw = JSON.parse(trimmed);
+    }
+    catch {
+        const match = trimmed.match(/(\{[\s\S]*\})/);
+        if (!match) {
+            throw new Error("Outline output is not valid JSON and contains no JSON object");
+        }
+        raw = JSON.parse(match[1]);
+    }
+    return OutlineSchema.parse(raw);
+}
+/**
+ * Parse a reviewer's JSON output and validate against the outline-review schema.
+ */
+export function parseOutlineReview(text) {
+    const trimmed = text.trim();
+    let raw;
+    try {
+        raw = JSON.parse(trimmed);
+    }
+    catch {
+        const match = trimmed.match(/(\{[\s\S]*\})/);
+        if (!match) {
+            throw new Error("Reviewer output is not valid JSON and contains no JSON object");
+        }
+        raw = JSON.parse(match[1]);
+    }
+    return OutlineReviewSchema.parse(raw);
+}
+// ---------- Spec review verdict ----------
+//
+// Same three-verdict structure as the outline reviewer, with categories
+// tailored to document-level cohesion concerns.
+export const SpecReviewSchema = z.object({
+    coverage_gaps: z.array(z.string()).default([]),
+    framing_errors: z.array(z.string()).default([]),
+    cross_area_issues: z.array(z.string()).default([]),
+    internal_mechanics_drift: z.array(z.string()).default([]),
+    revisions: z.array(z.string()).default([]),
+    verdict: z.enum(VerdictValues),
+});
+export const SPEC_REVIEW_JSON_SCHEMA = {
+    type: "object",
+    properties: {
+        coverage_gaps: { type: "array", items: { type: "string" } },
+        framing_errors: { type: "array", items: { type: "string" } },
+        cross_area_issues: { type: "array", items: { type: "string" } },
+        internal_mechanics_drift: { type: "array", items: { type: "string" } },
+        revisions: { type: "array", items: { type: "string" } },
+        verdict: {
+            type: "string",
+            enum: VerdictValues,
+        },
+    },
+    required: [
+        "coverage_gaps",
+        "framing_errors",
+        "cross_area_issues",
+        "internal_mechanics_drift",
+        "revisions",
+        "verdict",
+    ],
+    additionalProperties: false,
+};
+export function parseSpecReview(text) {
+    const trimmed = text.trim();
+    let raw;
+    try {
+        raw = JSON.parse(trimmed);
+    }
+    catch {
+        const match = trimmed.match(/(\{[\s\S]*\})/);
+        if (!match) {
+            throw new Error("Spec reviewer output is not valid JSON and contains no JSON object");
+        }
+        raw = JSON.parse(match[1]);
+    }
+    return SpecReviewSchema.parse(raw);
+}
+//# sourceMappingURL=schemas.js.map

package/dist/codebase-to-spec/skill-install.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Skill installation logic for the codebase-to-spec skill.
+ *
+ * The skill is a thin conversational wrapper around `dotrequirements cts run`.
+ * It ships as a SKILL.md template bundled in the CLI package, and this module
+ * copies it into the host's skill directory (default: `.claude/skills/` for
+ * Claude Code).
+ *
+ * Host portability (CTS-SKILL-5): the install logic supports any host that
+ * follows the Agent Skills format. The default target is Claude Code's
+ * convention; `--target-dir` lets users place the skill anywhere.
+ *
+ * Requirements covered:
+ * - CTS-SKILL-1: skill artifact exists and points users at `dotrequirements cts run`
+ * - CTS-SKILL-5: install logic is host-agnostic and works on any host with
+ *   Agent Skills format support
+ */
+export type SkillInstallScope = "project" | "global" | "custom";
+export interface SkillInstallOptions {
+    /**
+     * Where to install:
+     * - `project` (default): `<projectRoot>/.claude/skills/codebase-to-spec/`
+     * - `global`: `~/.claude/skills/codebase-to-spec/`
+     * - `custom`: requires `targetDir`
+     */
+    scope?: SkillInstallScope;
+    /** Required when `scope === 'custom'`. The skill directory will be created here. */
+    targetDir?: string;
+    /** Project root (used when scope === 'project'). Defaults to cwd. */
+    projectRoot?: string;
+    /** Overwrite existing SKILL.md if present. Default false. */
+    overwrite?: boolean;
+}
+export interface SkillInstallResult {
+    /** Final on-disk path to SKILL.md. */
+    installedPath: string;
+    /** True if a new file was written; false if it was already in place (no overwrite). */
+    installed: boolean;
+    /** True if an existing file was replaced. */
+    overwrote: boolean;
+}
+/**
+ * Resolve the directory in which the skill should live, given the user's
+ * scope choice. The directory itself is the `codebase-to-spec/` skill dir;
+ * `SKILL.md` is written inside it.
+ */
+export declare function resolveSkillDir(options: SkillInstallOptions): string;
+/**
+ * Load the bundled SKILL.md template from the package.
+ */
+export declare function loadSkillTemplate(): string;
+/**
+ * Install (or refuse to overwrite) the codebase-to-spec SKILL.md at the
+ * resolved location.
+ */
+export declare function installSkill(options?: SkillInstallOptions): SkillInstallResult;
+//# sourceMappingURL=skill-install.d.ts.map

package/dist/codebase-to-spec/skill-install.js

@@ -0,0 +1,79 @@
+/**
+ * Skill installation logic for the codebase-to-spec skill.
+ *
+ * The skill is a thin conversational wrapper around `dotrequirements cts run`.
+ * It ships as a SKILL.md template bundled in the CLI package, and this module
+ * copies it into the host's skill directory (default: `.claude/skills/` for
+ * Claude Code).
+ *
+ * Host portability (CTS-SKILL-5): the install logic supports any host that
+ * follows the Agent Skills format. The default target is Claude Code's
+ * convention; `--target-dir` lets users place the skill anywhere.
+ *
+ * Requirements covered:
+ * - CTS-SKILL-1: skill artifact exists and points users at `dotrequirements cts run`
+ * - CTS-SKILL-5: install logic is host-agnostic and works on any host with
+ *   Agent Skills format support
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { loadTemplate } from "../utils/templates.js";
+/**
+ * Resolve the directory in which the skill should live, given the user's
+ * scope choice. The directory itself is the `codebase-to-spec/` skill dir;
+ * `SKILL.md` is written inside it.
+ */
+export function resolveSkillDir(options) {
+    const scope = options.scope ?? "project";
+    switch (scope) {
+        case "project": {
+            const root = options.projectRoot ?? process.cwd();
+            return join(root, ".claude", "skills", "codebase-to-spec");
+        }
+        case "global":
+            return join(homedir(), ".claude", "skills", "codebase-to-spec");
+        case "custom":
+            if (!options.targetDir) {
+                throw new Error('targetDir is required when scope === "custom"');
+            }
+            // Treat targetDir as the parent skills/ directory; create the
+            // skill subdir under it.
+            return join(resolve(options.targetDir), "codebase-to-spec");
+    }
+}
+/**
+ * Load the bundled SKILL.md template from the package.
+ */
+export function loadSkillTemplate() {
+    return loadTemplate("skills/codebase-to-spec/SKILL.md");
+}
+/**
+ * Install (or refuse to overwrite) the codebase-to-spec SKILL.md at the
+ * resolved location.
+ */
+export function installSkill(options = {}) {
+    const skillDir = resolveSkillDir(options);
+    const skillPath = join(skillDir, "SKILL.md");
+    const template = loadSkillTemplate();
+    const exists = existsSync(skillPath);
+    if (exists && !options.overwrite) {
+        // Idempotent no-op: if the on-disk content already matches the template,
+        // there's nothing to do and we shouldn't surface that as a conflict.
+        const onDisk = readFileSync(skillPath, "utf-8");
+        if (onDisk === template) {
+            return { installedPath: skillPath, installed: false, overwrote: false };
+        }
+        // Stale or hand-edited copy: refuse without --overwrite so we don't
+        // silently clobber user changes.
+        throw new Error(`SKILL.md already exists at ${skillPath} and differs from the bundled template. Pass --overwrite to replace it, or delete the file first.`);
+    }
+    mkdirSync(dirname(skillPath), { recursive: true });
+    writeFileSync(skillPath, template, "utf-8");
+    return {
+        installedPath: skillPath,
+        installed: true,
+        overwrote: exists,
+    };
+}
+//# sourceMappingURL=skill-install.js.map

package/dist/codebase-to-spec/slice.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Slice extraction: given a Repomix pack and a list of file paths (or
+ * directory-prefix paths), produce a smaller pack containing only the matching
+ * files.
+ *
+ * Pack format (from Repomix --style plain):
+ *
+ *   ================
+ *   File: path/to/file
+ *   ================
+ *   <file contents>
+ *
+ *   ================
+ *   File: next/file
+ *   ================
+ *   ...
+ *
+ * We preserve the pack header (everything before the first File: section) and
+ * the matching sections.
+ *
+ * Requirements covered:
+ * - CTS-SPEC-1: CLI fans out one specifier worker per area; each worker
+ *   receives a slice extracted from the uncompressed pack
+ */
+/**
+ * Return true when `path` matches one of the entries in `wanted`.
+ *
+ * Each entry can be:
+ * - An exact file path (e.g., `src/foo.ts`) — matches that exact path.
+ * - A directory prefix ending in `/` (e.g., `src/services/browser/`) — matches
+ *   any file under that directory tree.
+ */
+export declare function pathMatchesWanted(path: string, wanted: Iterable<string>): boolean;
+export interface SliceExtractionResult {
+    /** Number of file sections matched (and written to the output). */
+    matched: number;
+    /** Total number of file sections in the input pack. */
+    total: number;
+}
+/**
+ * Extract sections matching `wanted` from the pack at `inputPath` and write
+ * them to `outputPath`. Preserves the pack header (Repomix metadata).
+ */
+export declare function extractSlice(inputPath: string, outputPath: string, wanted: Iterable<string>): SliceExtractionResult;
+/**
+ * Pure variant operating on already-loaded text. Useful for tests.
+ */
+export declare function extractSliceFromText(text: string, outputPath: string, wanted: Iterable<string>): SliceExtractionResult;
+//# sourceMappingURL=slice.d.ts.map