productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/specDecisionSignals.js

@@ -0,0 +1,121 @@
+import { parseHypotheses } from "./specSections.js";
+function cleanField(value) {
+    return value
+        .replace(/[\u0000-\u001f\u007f]/g, " ")
+        .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1")
+        .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
+        .replace(/[*_`~]/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function markdownFenceMarker(line) {
+    const match = line.match(/^\s*(`{3,}|~{3,})/);
+    return match ? match[1][0] : null;
+}
+function expectedImpact(specText, source) {
+    const lines = specText.split(/\r?\n/);
+    let inSection = false;
+    let inComment = false;
+    let inFence = null;
+    let outcome = null;
+    let target = null;
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (inFence) {
+            if (markdownFenceMarker(line) === inFence)
+                inFence = null;
+            continue;
+        }
+        if (inComment) {
+            if (line.includes("-->"))
+                inComment = false;
+            continue;
+        }
+        if (line.includes("<!--")) {
+            if (!line.includes("-->"))
+                inComment = true;
+            continue;
+        }
+        const marker = markdownFenceMarker(line);
+        if (marker) {
+            inFence = marker;
+            continue;
+        }
+        if (/^##\s+/.test(line) && !/^###/.test(line)) {
+            inSection = /^##\s+Expected Impact\s*$/i.test(line);
+            continue;
+        }
+        if (!inSection)
+            continue;
+        const field = line.match(/^\s*-\s+(Outcome|Target):\s*(.*?)\s*$/i);
+        if (!field)
+            continue;
+        const value = cleanField(field[2]);
+        if (field[1].toLowerCase() === "outcome" && value && !outcome)
+            outcome = { value, line: i + 1 };
+        if (field[1].toLowerCase() === "target" && value && !target)
+            target = value;
+    }
+    if (!outcome)
+        return { status: "missing", label: "Impact not stated" };
+    return {
+        status: "recorded",
+        outcome: outcome.value,
+        target,
+        provenance: { source, section: "Expected Impact", line: outcome.line },
+    };
+}
+function hasEvidenceReference(evidence) {
+    if (!evidence)
+        return false;
+    return !/^(?:none|none recorded|not stated|n\/?a|unknown)$/i.test(evidence.trim());
+}
+function proofFor(hypothesis) {
+    const state = hypothesis.state?.trim().toLowerCase().replace(/-/g, "_") ?? null;
+    if (state === "supported" || state === "falsified") {
+        if (hasEvidenceReference(hypothesis.evidence)) {
+            return {
+                proof: state,
+                proofDetail: state === "supported" ? "The spec records supporting evidence." : "The spec records falsifying evidence.",
+            };
+        }
+        return {
+            proof: "untested",
+            proofDetail: `Authored as ${state}, but no evidence reference is recorded.`,
+        };
+    }
+    if (state === "untested") {
+        return { proof: "untested", proofDetail: "The spec records this hypothesis as untested." };
+    }
+    if (state === "not_assessable") {
+        return { proof: "not_assessable", proofDetail: "The spec marks this hypothesis not assessable." };
+    }
+    if (!state)
+        return { proof: "not_assessable", proofDetail: "No hypothesis state is recorded." };
+    return { proof: "not_assessable", proofDetail: `Unrecognized hypothesis state: ${hypothesis.state}.` };
+}
+function projectHypothesis(hypothesis, source) {
+    return {
+        status: "recorded",
+        id: hypothesis.id,
+        statement: hypothesis.statement,
+        authoredState: hypothesis.state,
+        validationRefs: hypothesis.validationRefs,
+        evidence: hypothesis.evidence,
+        ...proofFor(hypothesis),
+        provenance: { source, section: "Hypotheses", line: hypothesis.line },
+    };
+}
+export function deriveSpecDecisionSignals(specText, source = "spec.md") {
+    const hypotheses = parseHypotheses(specText).map((hypothesis) => projectHypothesis(hypothesis, source));
+    return {
+        expectedImpact: expectedImpact(specText, source),
+        primaryHypothesis: hypotheses[0] ?? {
+            status: "missing",
+            label: "Hypothesis missing",
+            proof: "not_assessable",
+            proofDetail: "No hypothesis is recorded in the spec.",
+        },
+        hypotheses,
+    };
+}

package/dist-public/src/specLinkedCommits.d.ts

@@ -0,0 +1,7 @@
+export declare const FOO_SPEC_TRAILER = "Foo-Spec";
+export declare const DEFAULT_BRAND_URL = "https://foo.example";
+export declare function resolveBrandUrl(root: string): string;
+export declare function buildTrailer(root: string, packetArg: string | undefined): string;
+export declare function hasFooSpecTrailer(message: string): boolean;
+export declare function specIdFromFooSpecTrailer(message: string): string | null;
+export declare function commitTrailerSignal(root: string): string[];

package/dist-public/src/specLinkedCommits.js

@@ -0,0 +1,107 @@
+// Spec-linked commits: brand foo in the commit stream by tying every build
+// commit to the spec packet it implements. Modeled on the DCO `Signed-off-by:`
+// and GitHub `Co-Authored-By:` trailers — a standard, greppable git trailer that
+// is additive to any existing commit-message convention. Frictionless to
+// generate, advisory to check (a signal, not a boundary).
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { gitRunOrNull } from "./gitRun.js";
+import { readJson } from "./jsonFile.js";
+import { NotFoundError, UsageError } from "./errorTaxonomy.js";
+export const FOO_SPEC_TRAILER = "Foo-Spec";
+// The trailer carries a discoverable pointer so a stranger who sees it in a
+// public commit can find foo (the key "Foo-Spec" reads as a placeholder on its
+// own, and productfoo is closed source, so the pointer is the only on-ramp). It is
+// configurable with a safe default: FOO_BRAND_URL wins, then package.json
+// foo.brandUrl (committed, repo-wide), then a reserved-TLD placeholder that is
+// obviously meant to be replaced.
+export const DEFAULT_BRAND_URL = "https://foo.example";
+// Build commits that change product substance should carry the trailer; pure
+// chores, merges, and docs-only commits are exempt.
+const BUILD_PATH_PREFIXES = ["src/", "specs/", "examples/", "skills/", "test/"];
+function readSpecId(packetDir) {
+    const tasksPath = path.join(packetDir, "tasks.yaml");
+    if (!existsSync(tasksPath))
+        return null;
+    const match = readFileSync(tasksPath, "utf8").match(/^spec_id:\s*(\S+)\s*$/m);
+    return match ? match[1] : null;
+}
+function resolvePacket(root, packetArg) {
+    for (const candidate of [packetArg, path.join("specs", packetArg), path.join("examples", packetArg)]) {
+        const dir = path.resolve(root, candidate);
+        if (existsSync(dir) && existsSync(path.join(dir, "tasks.yaml")))
+            return dir;
+    }
+    return null;
+}
+export function resolveBrandUrl(root) {
+    const env = process.env.FOO_BRAND_URL;
+    if (env && env.trim())
+        return env.trim();
+    try {
+        const pkgPath = path.join(root, "package.json");
+        if (existsSync(pkgPath)) {
+            const pkg = readJson(pkgPath);
+            const url = pkg.foo?.brandUrl;
+            if (typeof url === "string" && url.trim())
+                return url.trim();
+        }
+    }
+    catch {
+        // fall through to the default
+    }
+    return DEFAULT_BRAND_URL;
+}
+export function buildTrailer(root, packetArg) {
+    if (!packetArg)
+        throw new UsageError("packet missing — usage: foo commit-trailer <packet>", "E_PACKET_DIR_MISSING");
+    const packetDir = resolvePacket(root, packetArg);
+    if (!packetDir)
+        throw new NotFoundError(`packet directory not found: ${packetArg}`, "E_PACKET_NOT_FOUND");
+    const specId = readSpecId(packetDir);
+    if (!specId)
+        throw new NotFoundError(`could not read spec_id from ${packetArg}/tasks.yaml`, "E_SPEC_NOT_FOUND");
+    const rel = path.relative(root, packetDir) || packetArg;
+    return `${FOO_SPEC_TRAILER}: ${rel} (${specId}) ${resolveBrandUrl(root)}\n`;
+}
+function inspectHead(root) {
+    const message = gitRunOrNull(["log", "-1", "--pretty=%B"], { cwd: root });
+    if (message === null)
+        return null;
+    const shown = gitRunOrNull(["show", "--name-only", "--pretty=format:", "HEAD"], { cwd: root });
+    if (shown === null)
+        return null;
+    const files = shown
+        .split(/\r?\n/)
+        .filter((line) => line.trim().length > 0);
+    return { message, files };
+}
+export function hasFooSpecTrailer(message) {
+    return new RegExp(`^${FOO_SPEC_TRAILER}:\\s*\\S`, "m").test(message);
+}
+// Extract the spec_id a commit declares via its Foo-Spec trailer, if any:
+// `Foo-Spec: specs/<packet> (<spec-id>) <url>` → "<spec-id>". This is the
+// authoritative PR→packet linkage for github-integration-v0 (D-009).
+export function specIdFromFooSpecTrailer(message) {
+    const m = message.match(new RegExp(`^${FOO_SPEC_TRAILER}:\\s*\\S+\\s*\\(([^)]+)\\)`, "m"));
+    return m ? m[1].trim() : null;
+}
+function isBuildCommit(files) {
+    return files.some((file) => BUILD_PATH_PREFIXES.some((prefix) => file.startsWith(prefix)));
+}
+// Advisory signal: if the most recent commit changed product substance but
+// carries no Foo-Spec trailer, surface it. Never blocks.
+export function commitTrailerSignal(root) {
+    const head = inspectHead(root);
+    if (!head)
+        return [];
+    if (!isBuildCommit(head.files))
+        return [];
+    if (hasFooSpecTrailer(head.message))
+        return [];
+    const subject = head.message.split(/\r?\n/)[0] ?? "";
+    return [
+        `HEAD build commit has no ${FOO_SPEC_TRAILER} trailer: "${subject}". Add one with \`foo commit-trailer <packet>\`, ` +
+            `or record a deliberate exemption with \`${FOO_SPEC_TRAILER}: none (<reason>)\`.`,
+    ];
+}

package/dist-public/src/specSections.d.ts

@@ -0,0 +1,105 @@
+import { type ProjectedQuestion } from "./questionModel.js";
+export declare const ANCHOR_KINDS: readonly ["R", "OQ", "D", "V", "RISK", "H"];
+export type AnchorKind = (typeof ANCHOR_KINDS)[number];
+export interface RequirementHeading {
+    id: string;
+    title: string;
+}
+export interface SpecAnchor {
+    kind: AnchorKind;
+    id: string;
+    line: number;
+    form: "heading" | "bullet";
+    title: string;
+}
+/**
+ * Tolerant read over the whole spec: every anchor of every kind, with line
+ * numbers. Requirement headings count anywhere (historical behavior); bullet
+ * anchors count only inside their home section.
+ */
+export declare function parseAnchors(specText: string): SpecAnchor[];
+/**
+ * All requirements — heading form anywhere plus bullet form inside
+ * `## Requirements`. Kept as the historical export name; every surface that
+ * links or counts requirements goes through here (R-001: no private regexes).
+ */
+export declare function parseRequirementHeadings(specText: string): RequirementHeading[];
+export declare function requirementIds(specText: string): string[];
+export interface OpenQuestion {
+    id: string | null;
+    text: string;
+    title: string;
+}
+export declare function parseOpenQuestions(specText: string): OpenQuestion[];
+export interface ParsedHypothesis {
+    id: string;
+    statement: string;
+    state: string | null;
+    validationRefs: string[];
+    evidence: string | null;
+    line: number;
+}
+/** Optional authored hypotheses, in document order, with no inferred fields. */
+export declare function parseHypotheses(specText: string): ParsedHypothesis[];
+export type DecisionTarget = {
+    kind: "packet";
+} | {
+    kind: "task";
+    id: string;
+};
+export interface PacketDecisionRequest {
+    id: string;
+    why_now: string;
+    unblocks: DecisionTarget;
+    answer_effect: string;
+    question: ProjectedQuestion;
+}
+export type DecisionFindingCode = "decision.missing_id" | "decision.missing_field" | "decision.invalid_confidence" | "decision.invalid_option" | "decision.missing_opt_out" | "decision.unknown_unblocks";
+export interface DecisionFinding {
+    code: DecisionFindingCode;
+    line: number;
+    text: string;
+    detail: string;
+}
+export interface DecisionParseResult {
+    requests: PacketDecisionRequest[];
+    findings: DecisionFinding[];
+}
+type DecisionParseOptions = {
+    taskIds?: Iterable<string>;
+};
+export declare function parseDecisionRequests(specText: string, options?: DecisionParseOptions): DecisionParseResult;
+export declare function decisionRequestAuthoringComment(): string;
+export type GrammarFindingCode = "grammar.duplicate_id" | "grammar.malformed_id" | "grammar.missing_id" | "grammar.unparsed_candidate";
+export interface GrammarFinding {
+    code: GrammarFindingCode;
+    line: number;
+    text: string;
+    detail: string;
+}
+export interface RequirementGrammar {
+    headingForm: boolean;
+    bulletForm: boolean;
+}
+export declare function requirementGrammarOf(anchors: SpecAnchor[]): RequirementGrammar;
+export declare function lintAnchors(specText: string): GrammarFinding[];
+/** Next free ID for a kind, zero-padded (`R-001` style), never reusing a
+ * number any existing anchor holds in any spelling. */
+export declare function nextAnchorId(kind: AnchorKind, existing: SpecAnchor[]): string;
+export declare function formatRequirementHeading(id: string, title: string): string;
+export declare function formatAnchorBullet(id: string, text: string): string;
+export interface Insertion {
+    line: number;
+    column: number;
+    id: string;
+    token: string;
+}
+export interface MigrateResult {
+    text: string;
+    insertions: Insertion[];
+    proofOk: boolean;
+}
+/** Remove exactly the recorded tokens — the mechanical proof's inverse. */
+export declare function stripInsertions(text: string, insertions: Insertion[]): string;
+export declare function migrateSpecText(specText: string): MigrateResult;
+export {};