@ogygie/cli 0.1.0

package/templates/project/scripts/verify-specs.ts

@@ -0,0 +1,222 @@
+/**
+ * @intent CI gate `pnpm ogygie:verify-specs`: every `specs/<feature>.spec.md`
+ * must carry a valid frontmatter (SpecFrontmatterSchema), the canonical FRENCH
+ * sections in order (specs are human-facing documents — DECISIONS.md D11), and
+ * respect the lifecycle rule (draft → no code, implemented → manifest says
+ * "delivered"). Frontmatter is deliberately restricted to scalars and inline
+ * arrays — the format is owned by @ogygie/core/spec (parseSpecFrontmatter),
+ * which REFUSES what it cannot read (D22 hardening, born with its mutation
+ * tests in packages/ogygie-core/src/spec.schema.test.ts) — this gate only
+ * reports.
+ * It also refuses any reference to a decision `D<n>` absent from the decision
+ * files — DECISIONS.md (framework) and DECISIONS.product.md (product), one
+ * GLOBAL numbering since the Phase 3 split — in a spec (frontmatter `refs` or
+ * body), in AGENTS.md or in AGENTS.product.md: a rule founded on a decision
+ * nobody took is silent documentary drift. A decision id declared in BOTH
+ * files is refused too (ambiguous citation). Logic and mutation tests in
+ * @ogygie/core/decision-refs.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  SECTIONS_SPEC_OBLIGATOIRES,
+  SpecFrontmatterSchema,
+  parseSpecFrontmatter,
+} from "@ogygie/core/spec";
+import {
+  findDuplicateDecisionIds,
+  findUnknownDecisionReferences,
+  parseKnownDecisionIds,
+} from "@ogygie/core/decision-refs";
+import { OgygieManifestSchema } from "@ogygie/core/manifest";
+import { ogygieError, type OgygieError } from "@ogygie/core/errors";
+
+const ROOT = new URL("..", import.meta.url).pathname;
+const SPECS_FOLDER = "specs";
+/** One global D<n> numbering across the two files (Phase 3 split, D10 rule 4). */
+const DECISIONS_FILES = ["DECISIONS.md", "DECISIONS.product.md"];
+/** Documents whose decision citations are checked, besides the specs. */
+const AGENTS_FILES = ["AGENTS.md", "AGENTS.product.md"];
+const problems: OgygieError[] = [];
+
+function report(input: Parameters<typeof ogygieError>[0]): void {
+  problems.push(ogygieError(input));
+}
+
+const manifest = OgygieManifestSchema.parse(
+  JSON.parse(readFileSync(join(ROOT, "ogygie.manifest.json"), "utf8")),
+);
+const apiApp = manifest.apps.find((app) => app.type === "api");
+
+const specFiles = readdirSync(join(ROOT, SPECS_FOLDER)).filter(
+  (fileName) => fileName.endsWith(".spec.md") && !fileName.startsWith("_"),
+);
+
+for (const fileName of specFiles) {
+  const specPath = join(SPECS_FOLDER, fileName);
+  const content = readFileSync(join(ROOT, specPath), "utf8");
+  const expectedId = fileName.replace(/\.spec\.md$/, "");
+
+  const frontmatterBlock = /^---\n([\s\S]*?)\n---/.exec(content);
+  if (frontmatterBlock === null || frontmatterBlock[1] === undefined) {
+    report({
+      code: "SPEC_FRONTMATTER_MISSING",
+      message: `Spec ${fileName} has no YAML frontmatter between --- markers.`,
+      file: specPath,
+      cause: "file does not start with a --- ... --- block",
+      suggestedFix: "Add the frontmatter following specs/_TEMPLATE.spec.md.",
+    });
+    continue;
+  }
+
+  const parsedFrontmatter = parseSpecFrontmatter(frontmatterBlock[1]);
+  if (parsedFrontmatter.problems.length > 0) {
+    report({
+      code: "SPEC_FRONTMATTER_INVALID",
+      message: `Spec ${fileName} has an invalid frontmatter FORMAT.`,
+      file: specPath,
+      cause: parsedFrontmatter.problems.join(" ; "),
+      suggestedFix:
+        "Use `key: value` lines with scalars or INLINE arrays only, balanced quotes (D13) — see parseSpecFrontmatter in packages/ogygie-core/src/spec.schema.ts.",
+    });
+    continue;
+  }
+
+  const parsed = SpecFrontmatterSchema.safeParse(parsedFrontmatter.value);
+  if (!parsed.success) {
+    report({
+      code: "SPEC_FRONTMATTER_INVALID",
+      message: `Spec ${fileName} has an invalid frontmatter.`,
+      file: specPath,
+      cause: parsed.error.issues
+        .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+        .join(" ; "),
+      suggestedFix: "Fix the listed fields to match packages/ogygie-core/src/spec.schema.ts.",
+    });
+    continue;
+  }
+  const frontmatter = parsed.data;
+
+  if (frontmatter.id !== expectedId) {
+    report({
+      code: "SPEC_ID_MISMATCH",
+      message: `Spec ${fileName} declares id "${frontmatter.id}" — expected "${expectedId}".`,
+      file: specPath,
+      cause: `id=${frontmatter.id} ≠ filename ${expectedId}`,
+      suggestedFix: "Make the frontmatter id identical to the file name.",
+    });
+  }
+
+  let cursor = 0;
+  for (const section of SECTIONS_SPEC_OBLIGATOIRES) {
+    const position = content.indexOf(`\n${section}`, cursor);
+    if (position === -1) {
+      report({
+        code: "SPEC_SECTION_MISSING",
+        message: `Spec ${fileName} is missing section "${section}" (or it is out of order).`,
+        file: specPath,
+        cause: `"${section}" not found after offset ${cursor}`,
+        suggestedFix:
+          "Add the canonical sections in the order defined by SECTIONS_SPEC_OBLIGATOIRES.",
+      });
+    } else {
+      cursor = position + section.length;
+    }
+  }
+
+  const manifestFeature = manifest.features.find(
+    (feature) => feature.name === frontmatter.id,
+  );
+  const featureDir =
+    apiApp !== undefined && manifestFeature !== undefined
+      ? join(ROOT, apiApp.path, manifestFeature.folder)
+      : null;
+
+  if (frontmatter.status === "draft") {
+    const implemented =
+      (manifestFeature !== undefined && manifestFeature.status !== "skeleton") ||
+      (featureDir !== null && existsSync(featureDir));
+    if (implemented) {
+      report({
+        code: "SPEC_DRAFT_ALREADY_IMPLEMENTED",
+        message: `Spec ${fileName} is draft but an implementation exists.`,
+        file: specPath,
+        cause: "status=draft with code or a non-skeleton manifest entry",
+        suggestedFix:
+          "Move the spec to validated/implemented, or remove the premature implementation.",
+      });
+    }
+  }
+
+  if (frontmatter.status === "implemented") {
+    // D13: an implemented spec has nothing left pending — deferred must be empty.
+    if (frontmatter.deferred.length > 0) {
+      report({
+        code: "SPEC_IMPLEMENTED_WITH_DEFERRED",
+        message: `Spec ${fileName} is implemented but still defers ${frontmatter.deferred.length} behavior(s).`,
+        file: specPath,
+        cause: `deferred=[${frontmatter.deferred.join(" ; ")}]`,
+        suggestedFix:
+          "Implement the deferred behaviors (their blocking features now exist?) and empty `deferred`, or keep the spec in validated.",
+      });
+    }
+    if (manifestFeature === undefined || manifestFeature.status !== "delivered") {
+      report({
+        code: "SPEC_IMPLEMENTED_NOT_DELIVERED",
+        message: `Spec ${fileName} is implemented but the manifest does not say status "delivered".`,
+        file: specPath,
+        cause: `manifest status=${manifestFeature?.status ?? "absent"}`,
+        suggestedFix:
+          "Set the feature's status to delivered in the manifest, or keep the spec in validated.",
+      });
+    }
+  }
+}
+
+// --------------------------------------------- decision references (D28 lot)
+// Independent of the frontmatter checks above: a spec whose format is broken
+// may also cite a phantom decision, and both deserve to be said in one run.
+const decisionIdsPerFile = DECISIONS_FILES.map((fileName) =>
+  parseKnownDecisionIds(readFileSync(join(ROOT, fileName), "utf8")),
+);
+const knownDecisionIds = decisionIdsPerFile.flat();
+
+// Phase 3 split: one D<n> lives in exactly ONE of the two files — a duplicate
+// declaration would make every citation ambiguous.
+for (const duplicated of findDuplicateDecisionIds(decisionIdsPerFile)) {
+  report({
+    code: "DECISION_DECLARED_TWICE",
+    message: `Decision ${duplicated} is declared more than once across ${DECISIONS_FILES.join(" and ")}.`,
+    file: DECISIONS_FILES.join(" ; "),
+    cause: `heading "## ${duplicated} — …" found in more than one place`,
+    suggestedFix:
+      "Keep the decision in exactly one file (framework rules in DECISIONS.md, product rules in DECISIONS.product.md) — the D<n> numbering is global.",
+  });
+}
+
+const documentsCitingDecisions = [
+  ...specFiles.map((fileName) => join(SPECS_FOLDER, fileName)),
+  ...AGENTS_FILES,
+];
+
+for (const documentPath of documentsCitingDecisions) {
+  const content = readFileSync(join(ROOT, documentPath), "utf8");
+  for (const reference of findUnknownDecisionReferences(content, knownDecisionIds)) {
+    report({
+      code: "SPEC_UNKNOWN_DECISION_REFERENCE",
+      message: `${documentPath} cites decision ${reference.decision}, which does not exist in ${DECISIONS_FILES.join(" nor ")}.`,
+      file: documentPath,
+      cause: `${reference.decision} cited at ${documentPath}:${reference.line} ; declared decisions: ${knownDecisionIds.join(", ")}`,
+      suggestedFix: `Add the decision to DECISIONS.md (framework) or DECISIONS.product.md (product) if it was taken but never committed, or cite the decision that really founds this rule.`,
+    });
+  }
+}
+
+if (problems.length > 0) {
+  for (const problem of problems) {
+    console.error(JSON.stringify(problem, null, 2));
+  }
+  console.error(`\nogygie:verify-specs — ${problems.length} problème(s).`);
+  process.exit(1);
+}
+console.log(`ogygie:verify-specs — OK, ${specFiles.length} spec(s) conformes.`);

package/templates/project/specs/_TEMPLATE.spec.md

@@ -0,0 +1,37 @@
+---
+id: nom-de-la-feature
+status: draft
+depends_on: []
+priority: P1
+refs: []
+# Optionnel (D13) : comportements décrits mais bloqués par une feature à venir.
+# Une spec ne peut passer `implemented` que si cette liste est vide.
+# deferred: ["CODE_ERREUR (résumé) blockedBy:nom-de-la-feature"]
+---
+
+# @intent
+Le job-to-be-done de l'utilisateur en 3 lignes max. Pourquoi cette feature
+existe, pas comment elle est construite.
+
+# Comportements
+(prose en français ; codes d'erreur, noms de schémas et valeurs d'enum
+directement en anglais — D11/D14, ex. « ALORS OgygieError PLOT_CODE_ALREADY_USED »)
+- ÉTANT DONNÉ <contexte>
+  QUAND <action>
+  ALORS <résultat observable et vérifiable>
+
+# Contrats de données
+Esquisse des schémas (sera traduite en Zod dans schemas.ts) :
+- SomethingInputSchema: { champ: type, ... }
+- SomethingOutputSchema: { champ: type, ... }
+
+# États UI
+- vide / chargement / nominal / erreur
+(lister les états, composer avec design/patterns.md — jamais d'invention libre)
+
+# Non-objectifs
+Ce que la feature ne fait PAS. Anti-scope-creep, anti-hallucination.
+
+# Budget
+- P95 API < 100 ms hors I/O tierces
+- Aucune dépendance npm nouvelle sans justification

package/templates/project/tsconfig.base.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  }
+}

package/templates/project/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "lib": ["ES2023"],
+    "types": ["node"]
+  },
+  "include": ["scripts/**/*.ts"]
+}

package/templates/project/vitest.config.ts

@@ -0,0 +1,23 @@
+/**
+ * @intent Single Vitest entry point for the whole workspace, so that
+ * `pnpm test -- features/<nom>` filters by path from the repo root.
+ * Node bench by default; a front app's UI tests opt into jsdom per file
+ * (`@vitest-environment jsdom` docblock). `passWithNoTests` because a
+ * freshly-inited project has no feature yet — the loop must be green from
+ * the first commit.
+ */
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: [
+      "apps/**/src/**/*.test.{ts,tsx}",
+      "packages/**/src/**/*.test.{ts,tsx}",
+    ],
+    environment: "node",
+    passWithNoTests: true,
+    // A feature test run must stay under 10 s (AGENTS.md principle 7);
+    // individual tests get a tight budget so slowness is caught early.
+    testTimeout: 5_000,
+  },
+});