@stephansama/auto-readme 0.2.10 → 0.2.12

package/skills/auto-readme/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: auto-readme
+description: >
+  Auto-generate and update tables and lists in README files using HTML comment
+  markers. Supports WORKSPACE (monorepo package tables), ACTION (GitHub Action
+  inputs from action.yml), PKG (package.json dependency tables), ZOD (zod schema
+  reference tables), USAGE actions. Run via CLI or as a pre-commit hook with
+  --changes to process only modified READMEs.
+type: core
+library: "@stephansama/auto-readme"
+library_version: "1.0.0"
+sources:
+  - stephansama/packages:core/auto-readme/src/comment.ts
+  - stephansama/packages:core/auto-readme/src/data.ts
+  - stephansama/packages:core/auto-readme/src/plugin.ts
+  - stephansama/packages:core/auto-readme/src/schema.ts
+  - stephansama/packages:core/auto-readme/README.md
+---
+
+# auto-readme
+
+Keeps README files up to date by replacing content between HTML comment markers. Run manually, in CI, or as a pre-commit hook.
+
+## Comment syntax
+
+```md
+<!-- ACTION_TYPE [options] start -->
+<!-- ACTION_TYPE end -->
+```
+
+Content between markers is replaced on every run. Markers must be paired — every `start` needs a matching `end`.
+
+## Setup
+
+```sh
+pnpx @stephansama/auto-readme
+```
+
+Add configuration to `package.json`:
+
+```json
+{
+  "auto-readme": {
+    "disableEmojis": false,
+    "onlyShowPublicPackages": true
+  }
+}
+```
+
+Or use a standalone config file (`.autoreadmerc.json`, `.config/autoreadmerc.ts`, `autoreadme.config.ts`, etc.).
+
+## Core Patterns
+
+### Monorepo workspace table
+
+```md
+<!-- WORKSPACE start -->
+<!-- WORKSPACE end -->
+```
+
+Generates a table of all packages in the workspace with name, version badge, download badge, and description. Reads from the pnpm/npm workspace config.
+
+### GitHub Action inputs table
+
+```md
+<!-- ACTION start -->
+<!-- ACTION end -->
+```
+
+Place this comment in a README inside a directory that contains `action.yml` or `action.yaml`. Generates a table of action inputs with name, required, default, and description columns.
+
+### Package.json dependency table
+
+```md
+<!-- PKG start -->
+<!-- PKG end -->
+```
+
+Generates a table of dependencies and devDependencies from the nearest `package.json`. Pass `path=` to point to a different package.json:
+
+```md
+<!-- PKG path="../other-package" start -->
+<!-- PKG end -->
+```
+
+### Zod schema reference table
+
+```md
+<!-- ZOD path="./src/schema.js" start -->
+<!-- ZOD end -->
+```
+
+Generates a markdown reference table from the default export of the given file using `zod2md`. The `path=` parameter is required and must point to a file with a zod schema as its default export.
+
+### Pre-commit hook (changed files only)
+
+```sh
+# .husky/pre-commit
+auto-readme --changes
+```
+
+`--changes` (`-g`) only processes README files that are modified in the current git changeset. Use in pre-commit hooks to avoid re-processing the entire repo on every commit.
+
+## Common Mistakes
+
+### HIGH ZOD action used with LIST format
+
+Wrong:
+
+```md
+<!-- ZOD-LIST path="./src/schema.js" start -->
+<!-- ZOD-LIST end -->
+```
+
+Correct:
+
+```md
+<!-- ZOD path="./src/schema.js" start -->
+<!-- ZOD end -->
+```
+
+The ZOD action only supports TABLE format. Specifying LIST (e.g. `ZOD-LIST`) throws `"cannot display zod in list format"` at pipeline execution time.
+
+Source: `core/auto-readme/src/data.ts`
+
+### HIGH ZOD comment missing path= parameter
+
+Wrong:
+
+```md
+<!-- ZOD start -->
+<!-- ZOD end -->
+```
+
+Correct:
+
+```md
+<!-- ZOD path="./src/schema.js" start -->
+<!-- ZOD end -->
+```
+
+The ZOD data loader requires `path=` to locate the schema file. Without it, auto-readme throws `"no path found for zod table at markdown file <file>"`.
+
+Source: `core/auto-readme/src/data.ts`
+
+### HIGH ACTION comment without action.yml in the same directory
+
+Wrong:
+
+```md
+<!-- In docs/README.md, but no action.yml in docs/ -->
+<!-- ACTION start -->
+<!-- ACTION end -->
+```
+
+Correct:
+
+```md
+<!-- In the same directory as action.yml -->
+<!-- ACTION start -->
+<!-- ACTION end -->
+```
+
+The ACTION data loader looks for `action.yml` or `action.yaml` in the same directory as the README file. Place the ACTION comment in the README co-located with the action definition, or use PKG for dependency tables in other directories.
+
+Source: `core/auto-readme/src/data.ts:loadActionYaml`
+
+### MEDIUM Unclosed or mismatched comment markers
+
+Wrong:
+
+```md
+<!-- WORKSPACE start -->
+
+Some content
+
+<!-- WORKSPACE start -->  ← second start, no end
+```
+
+Correct:
+
+```md
+<!-- WORKSPACE start -->
+<!-- WORKSPACE end -->
+```
+
+The `remark-zone` processor requires matched `start`/`end` pairs. Unmatched or duplicated markers cause the zone transform to silently skip or corrupt the section without an error.
+
+Source: `core/auto-readme/src/plugin.ts`

package/cli.mjs

@@ -1,4 +0,0 @@
-#!/usr/bin/env node
-
-const cli = await import("./dist/index.mjs");
-await cli.run();

package/config/schema.cjs

@@ -1,127 +0,0 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-//#region \0rolldown/runtime.js
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-		key = keys[i];
-		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
-			get: ((k) => from[k]).bind(null, key),
-			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-		});
-	}
-	return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
-	value: mod,
-	enumerable: true
-}) : target, mod));
-//#endregion
-let zod = require("zod");
-zod = __toESM(zod, 1);
-//#region src/schema.ts
-const actionsSchema = zod.enum([
-	"ACTION",
-	"PKG",
-	"USAGE",
-	"WORKSPACE",
-	"ZOD"
-]).meta({ description: "Comment action options" });
-const formatsSchema = zod.enum(["LIST", "TABLE"]).default("TABLE");
-const languageSchema = zod.enum(["JS", "RS"]).default("JS");
-const headingsSchema = zod.enum([
-	"default",
-	"description",
-	"devDependency",
-	"downloads",
-	"name",
-	"private",
-	"required",
-	"version"
-]).meta({ description: "Table heading options" });
-const tableHeadingsSchema = zod.record(actionsSchema, headingsSchema.array().optional()).default({
-	ACTION: [
-		"name",
-		"required",
-		"default",
-		"description"
-	],
-	PKG: [
-		"name",
-		"version",
-		"devDependency"
-	],
-	USAGE: [],
-	WORKSPACE: [
-		"name",
-		"version",
-		"downloads",
-		"description"
-	],
-	ZOD: []
-}).meta({ description: "Table heading action configuration" });
-const templatesSchema = zod.object({
-	downloadImage: zod.string().trim().default("https://img.shields.io/npm/dw/{{name}}?labelColor=211F1F"),
-	emojis: zod.record(headingsSchema, zod.string().trim()).default({
-		default: "⚙️",
-		description: "📝",
-		devDependency: "💻",
-		downloads: "📥",
-		name: "🏷️",
-		private: "🔒",
-		required: "",
-		version: ""
-	}).meta({ description: "Table heading emojis used when enabled" }),
-	registryUrl: zod.string().trim().default("https://www.npmjs.com/package/{{name}}"),
-	versionImage: zod.string().trim().default("https://img.shields.io/npm/v/{{uri_name}}?logo=npm&logoColor=red&color=211F1F&labelColor=211F1F")
-});
-const defaultTemplates = templatesSchema.parse({});
-const defaultTableHeadings = tableHeadingsSchema.parse(void 0);
-const configSchema = zod.object({
-	affectedRegexes: zod.array(zod.string().trim()),
-	collapseHeadings: zod.array(zod.string().trim()),
-	defaultLanguage: languageSchema.meta({
-		alias: "l",
-		description: "Default language to infer projects from"
-	}),
-	disableEmojis: zod.boolean().default(false).meta({
-		alias: "e",
-		description: "Whether or not to use emojis in markdown table headings"
-	}),
-	disableMarkdownHeadings: zod.boolean().default(false).meta({ description: "Whether or not to display markdown headings" }),
-	enablePrettier: zod.boolean().default(true).meta({ description: "Whether or not to use prettier to format the files" }),
-	enableToc: zod.boolean().default(false).meta({
-		alias: "t",
-		description: "generate table of contents for readmes"
-	}),
-	enableUsage: zod.boolean().default(false).meta({ description: "Whether or not to enable usage plugin" }),
-	headings: tableHeadingsSchema.optional().default(defaultTableHeadings).describe("List of headings for different table outputs"),
-	onlyReadmes: zod.boolean().default(true).meta({
-		alias: "r",
-		description: "Whether or not to only traverse readmes"
-	}),
-	onlyShowPublicPackages: zod.boolean().default(false).meta({
-		alias: "p",
-		description: "Only show public packages in workspaces"
-	}),
-	removeScope: zod.string().trim().default("").meta({ description: "Remove common workspace scope" }),
-	templates: templatesSchema.optional().default(defaultTemplates).describe("Handlebars templates used to fuel list and table generation"),
-	tocHeading: zod.string().trim().default("Table of contents").meta({ description: "Markdown heading used to generate table of contents" }),
-	usageFile: zod.string().trim().default("").meta({ description: "Workspace level usage file" }),
-	usageHeading: zod.string().trim().default("Usage").meta({ description: "Markdown heading used to generate usage example" }),
-	verbose: zod.boolean().default(false).meta({
-		alias: "v",
-		description: "whether or not to display verbose logging"
-	})
-}).optional();
-//#endregion
-exports.actionsSchema = actionsSchema;
-exports.configSchema = configSchema;
-exports.defaultTableHeadings = defaultTableHeadings;
-exports.defaultTemplates = defaultTemplates;
-exports.formatsSchema = formatsSchema;
-exports.languageSchema = languageSchema;

package/config/schema.d.cts

@@ -1,130 +0,0 @@
-import * as z from "zod";
-
-//#region src/schema.d.ts
-declare const actionsSchema: z.ZodEnum<{
-  ACTION: "ACTION";
-  PKG: "PKG";
-  USAGE: "USAGE";
-  WORKSPACE: "WORKSPACE";
-  ZOD: "ZOD";
-}>;
-declare const formatsSchema: z.ZodDefault<z.ZodEnum<{
-  LIST: "LIST";
-  TABLE: "TABLE";
-}>>;
-declare const languageSchema: z.ZodDefault<z.ZodEnum<{
-  JS: "JS";
-  RS: "RS";
-}>>;
-declare const defaultTemplates: {
-  downloadImage: string;
-  emojis: Record<"description" | "default" | "devDependency" | "downloads" | "name" | "private" | "required" | "version", string>;
-  registryUrl: string;
-  versionImage: string;
-};
-declare const defaultTableHeadings: Record<"ACTION" | "PKG" | "USAGE" | "WORKSPACE" | "ZOD", ("description" | "default" | "devDependency" | "downloads" | "name" | "private" | "required" | "version")[] | undefined>;
-declare const _configSchema: z.ZodObject<{
-  affectedRegexes: z.ZodArray<z.ZodString>;
-  collapseHeadings: z.ZodArray<z.ZodString>;
-  defaultLanguage: z.ZodDefault<z.ZodEnum<{
-    JS: "JS";
-    RS: "RS";
-  }>>;
-  disableEmojis: z.ZodDefault<z.ZodBoolean>;
-  disableMarkdownHeadings: z.ZodDefault<z.ZodBoolean>;
-  enablePrettier: z.ZodDefault<z.ZodBoolean>;
-  enableToc: z.ZodDefault<z.ZodBoolean>;
-  enableUsage: z.ZodDefault<z.ZodBoolean>;
-  headings: z.ZodDefault<z.ZodOptional<z.ZodDefault<z.ZodRecord<z.ZodEnum<{
-    ACTION: "ACTION";
-    PKG: "PKG";
-    USAGE: "USAGE";
-    WORKSPACE: "WORKSPACE";
-    ZOD: "ZOD";
-  }>, z.ZodOptional<z.ZodArray<z.ZodEnum<{
-    description: "description";
-    default: "default";
-    devDependency: "devDependency";
-    downloads: "downloads";
-    name: "name";
-    private: "private";
-    required: "required";
-    version: "version";
-  }>>>>>>>;
-  onlyReadmes: z.ZodDefault<z.ZodBoolean>;
-  onlyShowPublicPackages: z.ZodDefault<z.ZodBoolean>;
-  removeScope: z.ZodDefault<z.ZodString>;
-  templates: z.ZodDefault<z.ZodOptional<z.ZodObject<{
-    downloadImage: z.ZodDefault<z.ZodString>;
-    emojis: z.ZodDefault<z.ZodRecord<z.ZodEnum<{
-      description: "description";
-      default: "default";
-      devDependency: "devDependency";
-      downloads: "downloads";
-      name: "name";
-      private: "private";
-      required: "required";
-      version: "version";
-    }>, z.ZodString>>;
-    registryUrl: z.ZodDefault<z.ZodString>;
-    versionImage: z.ZodDefault<z.ZodString>;
-  }, z.core.$strip>>>;
-  tocHeading: z.ZodDefault<z.ZodString>;
-  usageFile: z.ZodDefault<z.ZodString>;
-  usageHeading: z.ZodDefault<z.ZodString>;
-  verbose: z.ZodDefault<z.ZodBoolean>;
-}, z.core.$strip>;
-declare const configSchema: z.ZodOptional<z.ZodObject<{
-  affectedRegexes: z.ZodArray<z.ZodString>;
-  collapseHeadings: z.ZodArray<z.ZodString>;
-  defaultLanguage: z.ZodDefault<z.ZodEnum<{
-    JS: "JS";
-    RS: "RS";
-  }>>;
-  disableEmojis: z.ZodDefault<z.ZodBoolean>;
-  disableMarkdownHeadings: z.ZodDefault<z.ZodBoolean>;
-  enablePrettier: z.ZodDefault<z.ZodBoolean>;
-  enableToc: z.ZodDefault<z.ZodBoolean>;
-  enableUsage: z.ZodDefault<z.ZodBoolean>;
-  headings: z.ZodDefault<z.ZodOptional<z.ZodDefault<z.ZodRecord<z.ZodEnum<{
-    ACTION: "ACTION";
-    PKG: "PKG";
-    USAGE: "USAGE";
-    WORKSPACE: "WORKSPACE";
-    ZOD: "ZOD";
-  }>, z.ZodOptional<z.ZodArray<z.ZodEnum<{
-    description: "description";
-    default: "default";
-    devDependency: "devDependency";
-    downloads: "downloads";
-    name: "name";
-    private: "private";
-    required: "required";
-    version: "version";
-  }>>>>>>>;
-  onlyReadmes: z.ZodDefault<z.ZodBoolean>;
-  onlyShowPublicPackages: z.ZodDefault<z.ZodBoolean>;
-  removeScope: z.ZodDefault<z.ZodString>;
-  templates: z.ZodDefault<z.ZodOptional<z.ZodObject<{
-    downloadImage: z.ZodDefault<z.ZodString>;
-    emojis: z.ZodDefault<z.ZodRecord<z.ZodEnum<{
-      description: "description";
-      default: "default";
-      devDependency: "devDependency";
-      downloads: "downloads";
-      name: "name";
-      private: "private";
-      required: "required";
-      version: "version";
-    }>, z.ZodString>>;
-    registryUrl: z.ZodDefault<z.ZodString>;
-    versionImage: z.ZodDefault<z.ZodString>;
-  }, z.core.$strip>>>;
-  tocHeading: z.ZodDefault<z.ZodString>;
-  usageFile: z.ZodDefault<z.ZodString>;
-  usageHeading: z.ZodDefault<z.ZodString>;
-  verbose: z.ZodDefault<z.ZodBoolean>;
-}, z.core.$strip>>;
-type Config = Partial<z.infer<typeof _configSchema>>;
-//#endregion
-export { Config, actionsSchema, configSchema, defaultTableHeadings, defaultTemplates, formatsSchema, languageSchema };

package/dist/index.d.cts

@@ -1,4 +0,0 @@
-//#region src/index.d.ts
-declare function run(): Promise<void>;
-//#endregion
-export { run };