@popoverai/dotrequirements 0.33.0 → 0.34.1

package/dist/sync/solution-documents.js

@@ -0,0 +1,135 @@
+/**
+ * Where a solution's documents live, the sync's half (SOLDOC; the decision
+ * is in docs/working/four-areas-prototype.md, "Where a solution's documents
+ * live"). A document that belongs to a solution and is not a requirements
+ * document lives in a solution directory, `.requirements/solutions/<solution>/`,
+ * named for its outcome; the `.requirements.md` name is what makes a file a
+ * requirements document, wherever it sits. A new file declares its belonging
+ * by its path; once the frontmatter carries it, the frontmatter is the truth.
+ */
+import * as path from "node:path";
+import { sanitizeFileName } from "./local-files.js";
+export const SOLUTIONS_DIR = "solutions";
+/** The solution directory a file sits directly in, if any (SOLDOC-8.1). */
+export function solutionDirOf(filePath) {
+    const parts = filePath.split(/[\\/]/);
+    const fileName = parts.at(-1);
+    const solutionSlug = parts.at(-2);
+    if (!fileName ||
+        !solutionSlug ||
+        parts.at(-3) !== SOLUTIONS_DIR ||
+        parts.at(-4) !== ".requirements" ||
+        !fileName.endsWith(".md")) {
+        return undefined;
+    }
+    return { solutionSlug, outcomeSlug: stemOf(fileName) };
+}
+/** `pitch` for `pitch.md` and for `pitch.requirements.md`. */
+export function stemOf(fileName) {
+    return fileName.replace(/\.requirements\.md$/, "").replace(/\.md$/, "");
+}
+/** SOLDOC-3: the name, never the content. Undefined for a file the rule doesn't reach. */
+export function requirementsDocByName(filePath) {
+    if (!solutionDirOf(filePath))
+        return undefined;
+    return filePath.endsWith(".requirements.md");
+}
+/** The directory a solution's documents live in, by name. */
+export function directoryOf(solution) {
+    return solution.directory ?? sanitizeFileName(solution.title);
+}
+/**
+ * What a pushed file belongs to (SOLDOC-4, SOLDOC-5): the frontmatter's
+ * belonging when it has one, else what its path claims, resolved against
+ * the project's solutions. A frontmatter that disagrees with the path is
+ * kept and reported; a path that resolves to nothing refuses the push.
+ */
+export function resolveBelonging(filePath, frontmatter, claim, solutions) {
+    const declared = frontmatter.solution && frontmatter.outcome
+        ? { solutionId: frontmatter.solution, outcome: frontmatter.outcome }
+        : undefined;
+    if (!claim)
+        return { belonging: declared };
+    const name = path.basename(filePath);
+    if (declared) {
+        // SOLDOC-5: the frontmatter wins; the path is layout. Say when they part.
+        const owner = solutions?.find((s) => s.solutionId === declared.solutionId);
+        if (owner && directoryOf(owner) !== claim.solutionSlug) {
+            return {
+                belonging: declared,
+                warning: `${name}: its path names a different solution than its frontmatter ("${owner.title}"); the frontmatter's belonging is kept.`,
+            };
+        }
+        // Read against the solution's other outcomes too: `spec-2` names Spec 2,
+        // not the Spec, when the plan has both.
+        if (outcomeNamedBy(claim.outcomeSlug, [
+            ...(owner?.outcomes ?? []),
+            declared.outcome,
+        ]) !== declared.outcome) {
+            return {
+                belonging: declared,
+                warning: `${name}: its filename names a different outcome than its frontmatter ("${declared.outcome}"); the frontmatter's belonging is kept.`,
+            };
+        }
+        return { belonging: declared };
+    }
+    // SOLDOC-4, SOLDOC-9: a new file's path is its declaration, read against
+    // each solution's own directory name.
+    const matches = (solutions ?? []).filter((s) => directoryOf(s) === claim.solutionSlug);
+    if (matches.length === 0) {
+        throw new Error(`${name}: its directory "${claim.solutionSlug}" matches no solution in the project, so it can't be placed. Name the directory as the solution's is named: its title as a slug, with its numeric suffix when an older solution has the same title.`);
+    }
+    if (matches.length > 1) {
+        throw new Error(`${name}: its directory "${claim.solutionSlug}" matches more than one solution (${matches.map((s) => `"${s.title}"`).join(", ")}), so it can't be placed.`);
+    }
+    const [solution] = matches;
+    const outcome = outcomeNamedBy(claim.outcomeSlug, solution.outcomes);
+    if (!outcome) {
+        throw new Error(`${name}: "${claim.outcomeSlug}" matches no outcome of "${solution.title}". Its plan produces: ${solution.outcomes.map((o) => `${o} (${sanitizeFileName(o)}.md)`).join(", ")}.`);
+    }
+    return { belonging: { solutionId: solution.solutionId, outcome } };
+}
+/**
+ * SOLDOC-4, SOLDOC-19: the outcome a file's stem names, of those given: the
+ * one whose slug the stem is, or else the one whose slug it is followed by a
+ * suffix from -2 up, as an outcome's later documents are named. So `spec-2`
+ * is Spec 2's when there is a Spec 2, and the Spec's otherwise.
+ */
+export function outcomeNamedBy(stem, outcomes) {
+    const plain = outcomes.find((o) => sanitizeFileName(o) === stem);
+    if (plain !== undefined)
+        return plain;
+    const later = /^(.+)-([1-9]\d*)$/.exec(stem);
+    if (!later || Number(later[2]) < 2)
+        return undefined;
+    return outcomes.find((o) => sanitizeFileName(o) === later[1]);
+}
+/**
+ * SOLDOC-6, SOLDOC-9, SOLDOC-19: where a pulled document that belongs to a
+ * solution lands when it has no file yet: in the solution's own directory,
+ * at the file name the backend gives it, which counts the outcome's other
+ * documents. A backend from before it was sent leaves it out, and the
+ * outcome's plain name stands in: its slug, with the `.requirements.md` name
+ * when it is a requirements document. When that file is taken, the document
+ * takes the outcome's next free name from -2 up.
+ */
+export function solutionDocumentPath(requirementsDir, solutionDirectory, outcome, isRequirementsDoc, fileName, taken = () => false) {
+    const suffix = isRequirementsDoc ? ".requirements.md" : ".md";
+    const directory = path.join(requirementsDir, SOLUTIONS_DIR, solutionDirectory || "solution");
+    const slug = sanitizeFileName(outcome) || "outcome";
+    // Only a plain file name of the document's kind, never a path.
+    const given = fileName &&
+        fileName === path.basename(fileName) &&
+        !fileName.startsWith(".") &&
+        stemOf(fileName) !== "" &&
+        fileName.endsWith(suffix) &&
+        (isRequirementsDoc || !fileName.endsWith(".requirements.md"))
+        ? fileName
+        : `${slug}${suffix}`;
+    let candidate = path.join(directory, given);
+    for (let n = 2; taken(candidate); n++) {
+        candidate = path.join(directory, `${slug}-${n}${suffix}`);
+    }
+    return candidate;
+}
+//# sourceMappingURL=solution-documents.js.map

package/dist/sync/types.d.ts

@@ -29,6 +29,9 @@ export interface LocalDocument {
     defaultPrefix?: string;
     /** document.attachments from frontmatter (ATTACH-10). */
     attachments?: Attachment[];
+    /** SOLDOC-5: the belonging the frontmatter declares. */
+    solution?: string;
+    outcome?: string;
     /** Frontmatter-stripped markdown body (the comparison unit, SYNC-ARCH-1). */
     body?: string;
     parseError?: string;
@@ -46,6 +49,18 @@ export interface CloudDocument {
     body: string;
     version: number;
     updatedAt: number;
+    /** SOLDOC-6: which solution and outcome it belongs to, with the solution's title and directory name. */
+    solution?: {
+        solutionId: string;
+        outcome: string;
+        title: string | null;
+        /** SOLDOC-9: the solution's directory name; absent from an older backend. */
+        directory?: string | null;
+        /** SOLDOC-19: the document's file name in that directory; absent from an older backend. */
+        fileName?: string | null;
+    };
+    /** SOLDOC-2/3: absent means a requirements document. */
+    isRequirementsDoc?: boolean;
 }
 export interface LocalSnapshot {
     documents: LocalDocument[];
@@ -54,6 +69,11 @@ export interface CloudSnapshot {
     projectName: string;
     projectSlug: string;
     documents: CloudDocument[];
+    /**
+     * SOLACCESS-2.2: whether the project's team has solutions, as the export
+     * read it; absent from an older backend, which reads as no.
+     */
+    solutions?: boolean;
 }
 /**
  * A single point of difference within a paired document, for verbose

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popoverai/dotrequirements",
-  "version": "0.33.0",
+  "version": "0.34.1",
   "description": "Requirements as testable, human-readable data — CLI and test harness for spec-driven development with AI coding agents",
   "type": "module",
   "bin": {
@@ -13,7 +13,8 @@
     "./schema": "./dist/schema/index.js",
     "./schema/browser": "./dist/schema/browser.js",
     "./style-guide": "./dist/requirements/style-guide.js",
-    "./greenfield": "./dist/requirements/greenfield.js"
+    "./greenfield": "./dist/requirements/greenfield.js",
+    "./rehearsal": "./dist/rehearsal/index.js"
   },
   "publishConfig": {
     "access": "public"