@avi2dg/checks 0.12.0 → 0.14.0

package/scripts/docs.ts

@@ -0,0 +1,90 @@
+#!/usr/bin/env bun
+import { Console, Effect } from "effect";
+import { ADR_DIRECTORY, judge, placementOf, placementProblem, type Placement } from "./doc-rules.ts";
+import { changedPaths, git, pathsAt, rangeEnds } from "./git.ts";
+import { runMain, Usage } from "./main.ts";
+import { readQuality } from "./quality-file.ts";
+
+type Finding = {
+  readonly path: string;
+  readonly line: number | undefined;
+  readonly message: string;
+};
+
+type Judged = {
+  readonly held: readonly string[];
+  readonly findings: readonly Finding[];
+  readonly advisory: ReadonlyMap<string, number>;
+};
+
+const NAME = "docs";
+const USAGE = "usage: docs.ts <ref> | <base-ref> <head-ref>";
+const MARKDOWN = [":(glob)**/*.md"];
+
+const judgeFile = Effect.fn("judgeFile")(function* (
+  root: string,
+  head: string,
+  path: string,
+  placement: Placement,
+  records: readonly string[],
+) {
+  const misplaced = placementProblem(placement);
+  if (misplaced !== undefined) return [{ path, line: undefined, message: misplaced }];
+  if (placement.type !== "judged") return [];
+  const text = yield* git(["show", `${head}:${path}`], root);
+  return judge(placement.kind, { path, text }, records).map(({ line, message }) => ({ path, line, message }));
+});
+
+const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head: string) {
+  const { quality } = yield* readQuality(root);
+  const touched = new Set(
+    (yield* changedPaths(base, head, MARKDOWN, root)).flatMap((change) => (change.kind === "deleted" ? [] : [change.path])),
+  );
+  const present = yield* pathsAt(head, MARKDOWN, root);
+  const records = present.filter((path) => path.startsWith(ADR_DIRECTORY));
+  const placed = present.map((path) => ({ path, placement: placementOf(path, quality.docs) }));
+  const judged = placed.filter(({ placement }) => placement.type !== "unjudged");
+  const findings = (yield* Effect.forEach(judged, ({ path, placement }) => judgeFile(root, head, path, placement, records), {
+    concurrency: 8,
+  })).flat();
+  const advisory = new Map<string, number>();
+  for (const { path } of findings.filter((finding) => !touched.has(finding.path))) advisory.set(path, (advisory.get(path) ?? 0) + 1);
+  return {
+    held: judged.map(({ path }) => path).filter((path) => touched.has(path)),
+    findings: findings.filter((finding) => touched.has(finding.path)),
+    advisory,
+  } satisfies Judged;
+});
+
+function describe({ path, line, message }: Finding): string {
+  return `  ${path}${line === undefined ? "" : `:${line}`}: ${message}`;
+}
+
+export function report({ held, findings, advisory }: Judged): string {
+  const verdict =
+    findings.length === 0
+      ? [`${NAME}: ${held.length} doc file(s) the range touches hold to their templates`]
+      : [`${NAME}: ${findings.length} violation(s) in the doc files the range touches:`, ...findings.map(describe)];
+  const notice =
+    advisory.size === 0
+      ? []
+      : [
+          `${NAME}: advisory, ${advisory.size} doc file(s) the range leaves alone do not hold to their templates yet:`,
+          ...[...advisory].map(([path, count]) => `  ${path}: ${count} violation(s)`),
+        ];
+  return [...verdict, ...notice].join("\n");
+}
+
+const docs = Effect.gen(function* () {
+  const [first, second, ...extra] = process.argv.slice(2);
+  if (first === undefined || extra.length > 0) return yield* new Usage({ message: USAGE });
+
+  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
+  const { base, head } = yield* rangeEnds(first, second, root);
+  const judged = yield* runDocs(root, base, head);
+
+  yield* Console.log(report(judged));
+  return judged.findings.length === 0;
+});
+
+if (import.meta.main) runMain(NAME, docs);

package/scripts/gates.ts

@@ -37,6 +37,7 @@ export const KIT_GATES = [
   { bin: "checks-comment-gate", script: "comment-gate.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-suppressions-ratchet", script: "suppressions-ratchet.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-ci-wiring", script: "ci-wiring.ts", reads: "tree", appliesTo: EVERY_REPOSITORY },
+  { bin: "checks-docs", script: "docs.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-quality", script: "quality.ts", reads: "tree", args: ["--check"], appliesTo: QUALITY_DECLARATION },
   { bin: "checks-size-budget", script: "size-budget.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-feature-owners", script: "feature-owners.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },

package/scripts/quality-file.ts

@@ -149,6 +149,26 @@ const AgentRules = Schema.Struct({
   }),
 );
 
+export const MODES = ["tutorial", "how-to", "reference", "explanation"] as const;
+export type Mode = (typeof MODES)[number];
+
+const pagesIn = (mode: string) =>
+  Schema.optionalKey(Schema.Array(PathGlob).annotate({ description: `The pages written as ${mode}` }));
+
+const Docs = Schema.Struct({
+  pages: Schema.optionalKey(
+    Schema.Struct({
+      tutorial: pagesIn("a tutorial, which teaches by building one thing"),
+      "how-to": pagesIn("a how-to, which walks one task"),
+      reference: pagesIn("reference, which describes a thing to be looked up"),
+      explanation: pagesIn("an explanation, which says why"),
+    } satisfies Record<Mode, unknown>).annotate({
+      description: "The Diátaxis mode of each page, whose template checks-docs holds the page to; a page under docs/ needs one",
+    }),
+  ),
+});
+export type Docs = typeof Docs.Type;
+
 export const Quality = Schema.Struct({
   $schema: Schema.optionalKey(Schema.String),
   defaultBranch: Schema.optionalKey(
@@ -171,6 +191,7 @@ export const Quality = Schema.Struct({
     }),
   ),
   agentRules: Schema.optionalKey(AgentRules),
+  docs: Schema.optionalKey(Docs.annotate({ description: "What checks-docs reads to map a doc file to its template" })),
 })
   .annotate({
     title: QUALITY_FILE,
@@ -200,7 +221,7 @@ export const Quality = Schema.Struct({
   );
 export type Quality = typeof Quality.Type;
 
-const LegacyManifest = Schema.Struct({
+export const LegacyManifest = Schema.Struct({
   ciWiring: Schema.optionalKey(
     Schema.Struct({
       gates: Schema.optionalKey(Schema.NonEmptyArray(Command)),

package/templates/adr.md

@@ -0,0 +1,29 @@
+# <number>. <The decision, as a sentence>
+
+Date: <YYYY-MM-DD, the day the record was written>
+
+## Status
+
+<Proposed, Accepted, Rejected, Deprecated, Superseded or Retired as its first word, then what it amends or what replaced it.>
+
+## Context
+
+<What forced a decision, and what was true when it was made.>
+
+## <Another part of the record, such as What was considered and rejected>
+
+<Leave this section out when the record needs no more.>
+
+<A section like this may also follow any section below it.>
+
+<Its text.>
+
+## Decision
+
+<What was decided, stated as what now holds.>
+
+## Consequences
+
+<Leave this section out when nothing follows from the decision but the decision.>
+
+<What follows from the decision, its cost included.>

package/templates/agents.md

@@ -0,0 +1,17 @@
+# Project agent memory
+
+<What this repository is, in one sentence, and that README.md holds what a person reads.>
+
+## <A topic an agent needs>
+
+<Leave this section out when the lead holds every constraint.>
+
+- <A constraint an agent cannot infer from the code, and the file that holds its detail.>
+
+## Maintaining this file
+
+Keep this file for knowledge useful to almost every future agent session in this project.
+Do not repeat what the codebase already shows.
+Point to the authoritative file or command instead.
+Prefer rewriting or pruning existing entries over appending new ones.
+When updating this file, preserve this bar for all agents and keep entries concise.

package/templates/changelog.md

@@ -0,0 +1,37 @@
+# Changelog
+
+Every release of <package>, newest first, written by the release from its conventional commits.
+
+## <version>
+
+Released <YYYY-MM-DD>.
+
+### Breaking changes
+
+<Leave this section out when the release holds no such commit.>
+
+- **<the commit's scope, when it has one>:** <its description>
+
+### Features
+
+<Leave this section out when the release holds no such commit.>
+
+- **<the commit's scope, when it has one>:** <its description>
+
+### Fixes
+
+<Leave this section out when the release holds no such commit.>
+
+- **<the commit's scope, when it has one>:** <its description>
+
+### Performance
+
+<Leave this section out when the release holds no such commit.>
+
+- **<the commit's scope, when it has one>:** <its description>
+
+### Reverts
+
+<Leave this section out when the release holds no such commit.>
+
+- **<the commit's scope, when it has one>:** <its description>

package/templates/claude.md

@@ -0,0 +1,2 @@
+<!-- Points Claude at AGENTS.md via import; edit AGENTS.md, not this file. -->
+@AGENTS.md

package/templates/explanation.md

@@ -0,0 +1,15 @@
+# <The idea this page explains, as a noun>
+
+<The question this page answers, and the short answer.>
+
+## <One strand of the answer>
+
+<Leave this section out when the lead holds the whole answer.>
+
+<The reasoning, the alternatives, and why they lost.>
+
+## Related topics
+
+<Leave this section out when there is no other page to send the reader to.>
+
+- [<page title>](<path to the page>)

package/templates/how-to.md

@@ -0,0 +1,33 @@
+# <Task, verb first>
+
+<Who does this, and when, in one or two sentences.>
+
+## Before you begin
+
+<Leave this section out when the task needs nothing set up first.>
+
+- <each prerequisite, with the version it is tested on>
+
+## <Part of the task, verb first>
+
+<Leave this section out when the page is one task, whose steps then follow the lead.>
+
+To <do the task>:
+
+1. <step>
+1. <step>
+
+## Troubleshooting
+
+<Leave this section out when no reader has met a failure worth naming yet.>
+
+### <The symptom, or the error text>
+
+<The cause.>
+<The resolution.>
+
+## Related topics
+
+<Leave this section out when there is no other page to send the reader to.>
+
+- [<page title>](<path to the page>)

package/templates/readme.md

@@ -0,0 +1,45 @@
+# <name>
+
+<The concept in two to four sentences: what this is, who it is for, why you would use it.>
+
+## Before you begin
+
+- <each prerequisite, with the version it is tested on>
+
+## Install
+
+To install <name>:
+
+1. <step>
+1. <step>
+
+<What you see when it worked.>
+
+## <Everyday task, verb first, or what the reader looks up>
+
+To <do the task>:
+
+1. <step>
+1. <step>
+
+<Or, for what the reader looks up, a table or a list with no steps.>
+
+## Where things are
+
+| Path | What it holds |
+| --- | --- |
+
+## Troubleshooting
+
+<Leave this section out when no reader has met a failure worth naming yet.>
+
+### <The symptom, or the error text>
+
+<The cause.>
+<The resolution.>
+
+## Related topics
+
+<Leave this section out when there is no other page to send the reader to.>
+
+- [<page title>](<path to the page>)

package/templates/reference.md

@@ -0,0 +1,15 @@
+# <The thing this page describes, as a noun>
+
+<What the thing is, in one sentence, and when a reader looks it up.>
+
+## <One part of it, as a noun>
+
+<Leave this section out when the lead and one table describe all of it.>
+
+<A table, a list or a short description, with no steps and no opinion.>
+
+## Related topics
+
+<Leave this section out when there is no other page to send the reader to.>
+
+- [<page title>](<path to the page>)

package/templates/tutorial.md

@@ -0,0 +1,31 @@
+# Tutorial: <Verb and what the reader builds>
+
+<What the reader builds, and what they learn on the way.>
+
+## Before you begin
+
+- <each prerequisite, with the version it is tested on>
+
+## <Step, verb first>
+
+To <do the task>:
+
+1. <step>
+1. <step>
+
+<What the reader sees now.>
+
+## Troubleshooting
+
+<Leave this section out when no reader has met a failure worth naming yet.>
+
+### <The symptom, or the error text>
+
+<The cause.>
+<The resolution.>
+
+## Related topics
+
+<Leave this section out when there is no other page to send the reader to.>
+
+- [<page title>](<path to the page>)