@trackunit/repo-checks 0.0.0-stage → 0.0.2

package/src/lib/doc-references/settings.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDocsSettings = exports.DEFAULT_DOCS_SETTINGS = exports.formatConfigIssues = exports.docReferencesConfigSchema = exports.strictObjectNamingKeys = exports.DEFAULT_BARE_FILENAMES = exports.DEFAULT_DIRECTORIES = exports.DEFAULT_CONSTRUCTS = exports.DEFAULT_IGNORE = void 0;
+const zod_1 = require("zod");
+const config_error_1 = require("../config-error");
+const placeholders_1 = require("./placeholders");
+/**
+ * Configuration for the doc-references check, validated with zod so a bad config fails with a
+ * message naming the offending key. Every default-bearing list takes `{ extend: [...] }` (add to
+ * the defaults) or `{ replace: [...] }` (swap them out, `[]` empties). A bare array is rejected
+ * because it can't say which of the two the author meant.
+ */
+/** Conventional generated-output locations, matched against the repo-relative path. */
+exports.DEFAULT_IGNORE = [
+    "**/dist/**",
+    "**/build/**",
+    "**/node_modules/**",
+    "**/coverage/**",
+    "**/*.{zip,tgz,tar.gz,jar,whl}",
+];
+const LIST_OVERRIDE_FORMS = "{ extend: [...] } to add to the defaults or { replace: [...] } to swap them out";
+const listOverrideSchema = (item) => zod_1.z
+    .object({
+    extend: zod_1.z.array(item).optional(),
+    replace: zod_1.z.array(item).optional(),
+}, {
+    errorMap: (issue, ctx) => issue.code === "invalid_type"
+        ? {
+            message: `expected ${LIST_OVERRIDE_FORMS}${Array.isArray(ctx.data) ? " (a bare array is ambiguous)" : ""}`,
+        }
+        : { message: ctx.defaultError },
+})
+    .strict()
+    .refine(value => (value.extend === undefined) !== (value.replace === undefined), {
+    message: `expected exactly one of extend or replace: ${LIST_OVERRIDE_FORMS}`,
+});
+/**
+ * A named convention, or a custom regex whose single capture group is the placeholder name. A regex
+ * that matches plain words, such as `(\w+)`, turns every segment into a wildcard and so disables
+ * the check.
+ */
+const placeholderConventionSchema = zod_1.z.string().superRefine((convention, ctx) => {
+    if (placeholders_1.NAMED_PLACEHOLDERS.some(named => named === convention))
+        return;
+    const groups = (0, placeholders_1.countCaptureGroups)(convention);
+    if (groups !== 1) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: `"${convention}" must be one of ${placeholders_1.NAMED_PLACEHOLDERS.join(", ")}, or a regex with exactly one capture group (${groups === undefined ? "it does not compile" : `found ${groups}`})`,
+        });
+    }
+});
+/**
+ * Links, images, and definitions are checked; inline code only on opt-in, since measured on manager
+ * about 96% of inline-code findings were false positives, mostly paths relative to an implied
+ * project root. A `constructs` setting overrides only the keys it names.
+ */
+exports.DEFAULT_CONSTRUCTS = { links: true, images: true, definitions: true, inlineCode: false };
+/** Provisional: whether extensionless references with a `/` (`libs/react/components/`) are checked. */
+exports.DEFAULT_DIRECTORIES = false;
+/**
+ * Provisional: whether inline code without a `/` (`` `README.md` ``) is checked. Link, image, and
+ * definition URLs without a `/` (`[x](README.md)`) are always checked; see `classify.ts`.
+ */
+exports.DEFAULT_BARE_FILENAMES = false;
+/** `'a', 'b'` for the keys of an `unrecognized_keys` issue. */
+const quoteKeys = (keys) => keys.map(key => `'${key}'`).join(", ");
+/** `a, b, or c`. */
+const orList = (items) => items.length > 1 ? `${items.slice(0, -1).join(", ")}, or ${items.at(-1)}` : items.join("");
+/**
+ * A strict object whose unknown keys are reported as `unknown <noun> 'key'; expected <valid keys>`,
+ * and whose wrong type as `expected <expected>`.
+ */
+const strictObjectNamingKeys = (shape, { noun, expected }) => zod_1.z
+    .object(shape, {
+    errorMap: (issue, ctx) => {
+        if (issue.code === "unrecognized_keys") {
+            return { message: `unknown ${noun} ${quoteKeys(issue.keys)}; expected ${orList(Object.keys(shape))}` };
+        }
+        return issue.code === "invalid_type" ? { message: `expected ${expected}` } : { message: ctx.defaultError };
+    },
+})
+    .strict();
+exports.strictObjectNamingKeys = strictObjectNamingKeys;
+/** A repo-relative glob: a leading `/` or `./` or a trailing `/` would silently match no document. */
+const excludeGlobSchema = zod_1.z.string().superRefine((glob, ctx) => {
+    if (glob.startsWith("/") || glob.startsWith("./")) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: `"${glob}" must not start with / or ./; globs are repo-relative, e.g. docs/sessions/**`,
+        });
+    }
+    else if (glob.endsWith("/")) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: `"${glob}" ends with /, which matches no document; use "${glob}**"`,
+        });
+    }
+});
+/** The `docReferences` section of `repo-checks.config.json`, as written. */
+exports.docReferencesConfigSchema = (0, exports.strictObjectNamingKeys)({
+    rootDir: zod_1.z.string().min(1).optional(),
+    ignore: listOverrideSchema(zod_1.z.string()).optional(),
+    exclude: zod_1.z
+        .array(excludeGlobSchema, {
+        errorMap: (issue, ctx) => issue.code === "invalid_type"
+            ? {
+                message: "expected an array of globs; exclude has no defaults, so it takes no { extend } or { replace }",
+            }
+            : { message: ctx.defaultError },
+    })
+        .optional(),
+    placeholders: listOverrideSchema(placeholderConventionSchema).optional(),
+    constructs: (0, exports.strictObjectNamingKeys)({
+        links: zod_1.z.boolean().optional(),
+        images: zod_1.z.boolean().optional(),
+        definitions: zod_1.z.boolean().optional(),
+        inlineCode: zod_1.z.boolean().optional(),
+    }, { noun: "construct", expected: "an object of booleans, e.g. { links, images, definitions, inlineCode }" }).optional(),
+    directories: zod_1.z.boolean().optional(),
+    bareFilenames: zod_1.z.boolean().optional(),
+}, { noun: "setting", expected: "an object of doc-references settings" });
+/** Every issue as `path: message`, `;`-separated, with `(root)` for the top level. */
+const formatConfigIssues = (error) => error.issues.map(issue => `${issue.path.length > 0 ? issue.path.join(".") : "(root)"}: ${issue.message}`).join("; ");
+exports.formatConfigIssues = formatConfigIssues;
+const applyOverride = (defaults, override) => {
+    if (override?.replace) {
+        return override.replace;
+    }
+    return [...defaults, ...(override?.extend ?? [])];
+};
+/** The resolved settings when no config is given. */
+exports.DEFAULT_DOCS_SETTINGS = {
+    rootDir: undefined,
+    ignore: exports.DEFAULT_IGNORE,
+    exclude: [],
+    placeholders: placeholders_1.DEFAULT_PLACEHOLDERS,
+    constructs: exports.DEFAULT_CONSTRUCTS,
+    directories: exports.DEFAULT_DIRECTORIES,
+    bareFilenames: exports.DEFAULT_BARE_FILENAMES,
+};
+/**
+ * Validate a raw doc-references config and resolve it onto the defaults. `undefined` yields
+ * {@link DEFAULT_DOCS_SETTINGS}.
+ *
+ * @throws {ConfigError} naming every offending key, when the config is invalid
+ */
+const parseDocsSettings = (raw) => {
+    if (raw === undefined) {
+        return exports.DEFAULT_DOCS_SETTINGS;
+    }
+    const parsed = exports.docReferencesConfigSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new config_error_1.ConfigError(`Invalid doc-references config: ${(0, exports.formatConfigIssues)(parsed.error)}`);
+    }
+    return {
+        rootDir: parsed.data.rootDir,
+        ignore: applyOverride(exports.DEFAULT_IGNORE, parsed.data.ignore),
+        exclude: parsed.data.exclude ?? [],
+        placeholders: applyOverride(placeholders_1.DEFAULT_PLACEHOLDERS, parsed.data.placeholders),
+        constructs: { ...exports.DEFAULT_CONSTRUCTS, ...parsed.data.constructs },
+        directories: parsed.data.directories ?? exports.DEFAULT_DIRECTORIES,
+        bareFilenames: parsed.data.bareFilenames ?? exports.DEFAULT_BARE_FILENAMES,
+    };
+};
+exports.parseDocsSettings = parseDocsSettings;
+//# sourceMappingURL=settings.js.map

package/src/lib/doc-references/suppressions.d.ts

@@ -0,0 +1,8 @@
+import { type MarkdownNode } from "./parse";
+/**
+ * The 1-based line whose references an ignore-next-line comment suppresses, the line after the
+ * comment ends, or `undefined` when `node` isn't one. In `.md` the comment is an HTML comment that
+ * is the whole `html` node; in `.mdx`, which has no HTML comments (one fails to parse), it is a
+ * comment-only `{/* ... *\/}` expression. Code blocks are leaves, so a comment inside one is text.
+ */
+export declare const ignoredNextLine: (node: MarkdownNode) => number | undefined;

package/src/lib/doc-references/suppressions.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ignoredNextLine = void 0;
+const parse_1 = require("./parse");
+/** `<!-- doc-references-ignore-next-line -->`, optionally with `: reason` before the `-->`. */
+const HTML_COMMENT_RE = /^<!--\s*doc-references-ignore-next-line(?:\s*:[\s\S]*?)?\s*-->$/u;
+/** `/* doc-references-ignore-next-line *\/`, optionally with `: reason`, as an MDX `{expression}`'s value. */
+const MDX_COMMENT_RE = /^\/\*\s*doc-references-ignore-next-line(?:\s*:[\s\S]*?)?\s*\*\/$/u;
+/**
+ * The 1-based line whose references an ignore-next-line comment suppresses, the line after the
+ * comment ends, or `undefined` when `node` isn't one. In `.md` the comment is an HTML comment that
+ * is the whole `html` node; in `.mdx`, which has no HTML comments (one fails to parse), it is a
+ * comment-only `{/* ... *\/}` expression. Code blocks are leaves, so a comment inside one is text.
+ */
+const ignoredNextLine = (node) => {
+    const end = node.position?.end.line;
+    const value = node.value?.trim();
+    if (end === undefined || value === undefined)
+        return undefined;
+    const isMarker = node.type === "html" ? HTML_COMMENT_RE.test(value) : (0, parse_1.isCommentExpression)(node) && MDX_COMMENT_RE.test(value);
+    return isMarker ? end + 1 : undefined;
+};
+exports.ignoredNextLine = ignoredNextLine;
+//# sourceMappingURL=suppressions.js.map

package/src/lib/format.d.ts

@@ -0,0 +1,13 @@
+import type { Finding } from "./doc-references/finding";
+export declare const OUTPUT_FORMATS: readonly ["text", "json"];
+/** How findings are printed: `text` lines for people, a `json` array for tools. */
+export type OutputFormat = (typeof OUTPUT_FORMATS)[number];
+/** An expected error as its message; anything else is a bug, so its stack is kept for the report. */
+export declare const formatError: (error: unknown) => string;
+/** One finding as `file:line:col  target  reason[  did you mean <suggestion>]`. */
+export declare const formatFinding: (finding: Finding) => string;
+/**
+ * Findings as `text` (one {@link formatFinding} line each, nothing when there are none) or as a
+ * `json` array of every Finding field (`[]` when there are none). Non-empty output ends in a newline.
+ */
+export declare const formatFindings: (findings: ReadonlyArray<Finding>, format: OutputFormat) => string;

package/src/lib/format.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatFindings = exports.formatFinding = exports.formatError = exports.OUTPUT_FORMATS = void 0;
+const config_1 = require("./config");
+const fs_errors_1 = require("./doc-references/fs-errors");
+const parse_1 = require("./doc-references/parse");
+exports.OUTPUT_FORMATS = ["text", "json"];
+const isExpectedError = (error) => error instanceof config_1.ConfigError ||
+    error instanceof parse_1.DocumentParseError ||
+    error instanceof fs_errors_1.ReadError ||
+    (0, fs_errors_1.isSystemError)(error);
+/** An expected error as its message; anything else is a bug, so its stack is kept for the report. */
+const formatError = (error) => !isExpectedError(error) && error instanceof Error && error.stack !== undefined
+    ? `${error.stack}\n`
+    : `Error: ${(0, fs_errors_1.errorMessage)(error)}\n`;
+exports.formatError = formatError;
+/** One finding as `file:line:col  target  reason[  did you mean <suggestion>]`. */
+const formatFinding = (finding) => [
+    `${finding.file}:${finding.line}:${finding.column}`,
+    finding.target,
+    finding.reason,
+    ...(finding.suggestion === undefined ? [] : [`did you mean ${finding.suggestion}`]),
+].join("  ");
+exports.formatFinding = formatFinding;
+/**
+ * Findings as `text` (one {@link formatFinding} line each, nothing when there are none) or as a
+ * `json` array of every Finding field (`[]` when there are none). Non-empty output ends in a newline.
+ */
+const formatFindings = (findings, format) => format === "json"
+    ? `${JSON.stringify(findings, null, 2)}\n`
+    : findings.map(finding => `${(0, exports.formatFinding)(finding)}\n`).join("");
+exports.formatFindings = formatFindings;
+//# sourceMappingURL=format.js.map