Add simpledoc check command

.github/workflows/checks.yaml

@@ -13,6 +13,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - uses: actions/setup-node@v4
         with:
           node-version: 24
@@ -22,3 +24,4 @@ jobs:
       - run: npm run format:check
       - run: npm run lint
       - run: npm test
+      - run: node dist-test/src/bin/simpledoc.js check

README.md

@@ -44,6 +44,28 @@ npx -y @simpledoc/simpledoc migrate
 
 This will start a step-by-step wizard to migrate existing documentation to SimpleDoc and add instructions to `AGENTS.md` to follow it.
 
+## CI / Enforcement
+
+To enforce SimpleDoc conventions in CI, add a step that fails when the repo needs migration:
+
+```bash
+npx -y @simpledoc/simpledoc check
+```
+
+### GitHub Actions example
+
+SimpleDoc relies on git history for timestamps/authors, so ensure the repo is not a shallow clone:
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+- uses: actions/setup-node@v4
+  with:
+    node-version: 24
+- run: npx -y @simpledoc/simpledoc check
+```
+
 ## Why?
 
 If you have been a developer for a while, the conventions described above should be familiar and common sense to you. For some weird reason, a crystallized definition such as this one does not exist online, e.g. the way [JSend](https://github.com/omniti-labs/jsend) does for API responses. So this is an attempt to fill that gap.

docs/HOW_TO_DOC.md

@@ -85,3 +85,4 @@ SimpleDoc Guidelines:
 - [ ] Timeless vs. dated classification is correct and filenames reflect the choice.
 - [ ] Front matter is complete and accurate.
 - [ ] Links to related documentation exist where applicable.
+- [ ] Run `npx -y @simpledoc/simpledoc check` (or `simpledoc check`) to verify SimpleDoc conventions.

src/cli/check.ts

@@ -0,0 +1,77 @@
+import process from "node:process";
+
+import {
+  formatActions,
+  planMigration,
+  type FrontmatterAction,
+  type ReferenceUpdateAction,
+  type RenameAction,
+} from "../migrator.js";
+import { MAX_STEP_FILE_PREVIEW_LINES, limitLines } from "./ui.js";
+
+function getErrorMessage(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+
+export async function runCheck(): Promise<void> {
+  try {
+    const plan = await planMigration();
+
+    const renames = plan.actions.filter(
+      (a): a is RenameAction => a.type === "rename",
+    );
+    const frontmatters = plan.actions.filter(
+      (a): a is FrontmatterAction => a.type === "frontmatter",
+    );
+    const references = plan.actions.filter(
+      (a): a is ReferenceUpdateAction => a.type === "references",
+    );
+
+    if (
+      renames.length === 0 &&
+      frontmatters.length === 0 &&
+      references.length === 0 &&
+      true
+    ) {
+      process.stdout.write("OK: repo matches SimpleDoc conventions.\n");
+      return;
+    }
+
+    process.stdout.write("SimpleDoc check failed.\n\n");
+
+    const summaryLines: string[] = [];
+    if (renames.length > 0)
+      summaryLines.push(
+        `- Rename/move Markdown files: ${renames.length} file${renames.length === 1 ? "" : "s"}`,
+      );
+    if (frontmatters.length > 0)
+      summaryLines.push(
+        `- Insert YAML frontmatter: ${frontmatters.length} file${frontmatters.length === 1 ? "" : "s"}`,
+      );
+    if (references.length > 0)
+      summaryLines.push(
+        `- Update references to renamed docs: ${references.length} file${references.length === 1 ? "" : "s"}`,
+      );
+
+    process.stdout.write(`${summaryLines.join("\n")}\n\n`);
+
+    if (renames.length + frontmatters.length + references.length > 0) {
+      const previewLines: string[] = [];
+      if (renames.length > 0) previewLines.push(formatActions(renames));
+      if (frontmatters.length > 0)
+        previewLines.push(formatActions(frontmatters));
+      if (references.length > 0) previewLines.push(formatActions(references));
+
+      const preview = previewLines.filter(Boolean).join("\n");
+      const limited = limitLines(preview, MAX_STEP_FILE_PREVIEW_LINES);
+      process.stdout.write(`${limited}\n\n`);
+    }
+
+    process.stdout.write("Run `simpledoc migrate` to fix.\n");
+    process.exitCode = 1;
+  } catch (err) {
+    process.stderr.write(`${getErrorMessage(err)}\n`);
+    process.exitCode = 1;
+  }
+}

src/cli/index.ts

@@ -1,6 +1,7 @@
 import process from "node:process";
 import { Command, CommanderError } from "commander";
 
+import { runCheck } from "./check.js";
 import { runMigrate } from "./migrate.js";
 
 type MigrateOptions = {
@@ -53,6 +54,13 @@ export async function runCli(argv: string[]): Promise<void> {
       await runMigrate(options);
     });
 
+  program
+    .command("check")
+    .description("Fail if the repo violates SimpleDoc conventions (use in CI).")
+    .action(async () => {
+      await runCheck();
+    });
+
   const rest = argv.slice(2);
   const argvToParse = shouldDefaultToMigrate(rest)
     ? [...argv.slice(0, 2), "migrate", ...rest]