@yukyu30/fluorite 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,226 @@
+/**
+ * Fluent, chainable assertions for a single frontmatter key.
+ *
+ * Each terminal matcher records one {@link RuleResult} on the parent
+ * {@link Recorder} and returns `this`, so matchers can be chained:
+ *
+ * ```ts
+ * fm.key("title").required().type("string").lengthMin(10);
+ * fm.key("tags").not.has("ng");
+ * ```
+ *
+ * The `.not` modifier negates only the next matcher, then resets.
+ */
+declare class KeyAssertion {
+    #private;
+    private readonly recorder;
+    private readonly key;
+    private readonly value;
+    private readonly present;
+    constructor(recorder: Recorder, key: string, value: unknown, present: boolean);
+    /** Negate the next matcher in the chain. */
+    get not(): this;
+    /** The raw value (resolved against the sentinel) used by matchers. */
+    private get resolved();
+    /**
+     * Record a result, applying the pending `.not` negation, then reset it.
+     */
+    private record;
+    /** Assert the key exists in the frontmatter. */
+    required(): this;
+    /** Alias of {@link required}. */
+    exists(): this;
+    /** Assert the value is of the given type. */
+    type(expected: ValueType): this;
+    /** Assert the value strictly equals `expected` (deep for arrays/objects). */
+    eq(expected: unknown): this;
+    /**
+     * Assert the value is an array whose every element is in `allowed` (enum).
+     *
+     * Designed for catching tag notation drift: define the canonical set once
+     * and any stray / mistyped value is reported.
+     *
+     * ```ts
+     * fm.key("tags").subsetOf(["ok", "release", "blog"]);
+     * ```
+     */
+    subsetOf(allowed: readonly unknown[]): this;
+    /** Alias of {@link subsetOf}. */
+    only(allowed: readonly unknown[]): this;
+    /**
+     * Apply matchers to every element of an array value.
+     *
+     * ```ts
+     * fm.key("tags").each.oneOf(["ok", "release"]);
+     * fm.key("tags").each.matches(/^[a-z0-9-]+$/);
+     * ```
+     */
+    get each(): EachAssertion;
+    /** Assert the value is one of `allowed` (enum). */
+    oneOf(allowed: readonly unknown[]): this;
+    /** Assert a string value matches the given regular expression. */
+    matches(pattern: RegExp): this;
+    /** Assert an array contains `item`, or a string contains the substring. */
+    has(item: unknown): this;
+    /** Assert an array/string contains all of `items`. */
+    hasAll(items: readonly unknown[]): this;
+    /** Assert an array/string contains at least one of `items`. */
+    hasAny(items: readonly unknown[]): this;
+    /** Assert the string/array length equals `n`. */
+    length(n: number): this;
+    /** Assert the string/array length is at least `n`. */
+    lengthMin(n: number): this;
+    /** Assert the string/array length is at most `n`. */
+    lengthMax(n: number): this;
+}
+/**
+ * Applies matchers to every element of an array frontmatter value.
+ *
+ * Obtained via {@link KeyAssertion.each}. Each terminal matcher records a
+ * single {@link RuleResult}: it passes only when the value is an array and
+ * every element satisfies the matcher; failures list the offending elements.
+ */
+declare class EachAssertion {
+    #private;
+    private readonly recorder;
+    private readonly key;
+    private readonly value;
+    constructor(recorder: Recorder, key: string, value: unknown, negated: boolean);
+    /** Negate the next matcher in the chain. */
+    get not(): this;
+    private record;
+    /** Every element must be one of `allowed` (enum over array contents). */
+    oneOf(allowed: readonly unknown[]): this;
+    /** Every element must be of the given type. */
+    type(expected: ValueType): this;
+    /** Every (string) element must match the pattern. */
+    matches(pattern: RegExp): this;
+}
+
+/**
+ * The `fm` object passed to a rule set. Holds the parsed frontmatter data,
+ * hands out {@link KeyAssertion} instances via {@link key}, and accumulates
+ * every {@link RuleResult} the matchers record.
+ */
+declare class Recorder {
+    readonly data: Record<string, unknown>;
+    readonly results: RuleResult[];
+    constructor(data: Record<string, unknown>);
+    /** Begin a chain of assertions against the given frontmatter key. */
+    key(name: string): KeyAssertion;
+    /** Internal: append a recorded rule result. */
+    push(result: RuleResult): void;
+}
+
+/** The set of value types understood by the `type()` matcher. */
+type ValueType = "string" | "number" | "boolean" | "array" | "object" | "null";
+/** Result of a single matcher invocation against one key. */
+interface RuleResult {
+    /** The frontmatter key that was inspected, e.g. `"tags"`. */
+    key: string;
+    /** The matcher name, e.g. `"has"` or `"lengthMin"`. */
+    rule: string;
+    /** Whether the check passed. */
+    ok: boolean;
+    /** Whether the matcher was reached through `.not`. */
+    negated: boolean;
+    /** Human readable description of the outcome. */
+    message: string;
+    /** The actual value found at `key`. */
+    value: unknown;
+    /** The expected value / argument passed to the matcher, if any. */
+    expected?: unknown;
+}
+/** Aggregated outcome of running a rule set against one frontmatter object. */
+interface CheckResult {
+    /** True when every recorded rule passed. */
+    ok: boolean;
+    /** Every rule result, in the order they were recorded. */
+    results: RuleResult[];
+    /** Only the failing rule results. */
+    failures: RuleResult[];
+    /** The parsed frontmatter data. */
+    data: Record<string, unknown>;
+}
+/** A rule set: receives the recorder (`fm`) and registers matchers. */
+type RulesFn = (fm: Recorder) => void;
+/** Configuration accepted by `defineConfig` / consumed by the CLI. */
+interface FluoriteConfig {
+    /** Glob patterns of Markdown files to check. */
+    include?: string[];
+    /** Glob patterns to exclude. */
+    exclude?: string[];
+    /** The rule set applied to every file's frontmatter. */
+    rules: RulesFn;
+}
+
+/**
+ * Run a rule set against the frontmatter of a Markdown source string.
+ *
+ * Never throws: malformed YAML or a missing frontmatter block is surfaced as a
+ * failing {@link RuleResult} so results can always be collected and reported.
+ *
+ * ```ts
+ * const result = check(markdown, (fm) => {
+ *   fm.key("title").required().lengthMin(10);
+ *   fm.key("tags").not.has("ng");
+ * });
+ * if (!result.ok) console.error(result.failures);
+ * ```
+ */
+declare function check(source: string, rules: RulesFn): CheckResult;
+/** Run a rule set against already-parsed frontmatter data. */
+declare function checkData(data: Record<string, unknown>, rules: RulesFn): CheckResult;
+
+/**
+ * Identity helper for authoring a config file with full type inference:
+ *
+ * ```ts
+ * import { defineConfig } from "fluorite";
+ * export default defineConfig({
+ *   include: ["docs/**\/*.md"],
+ *   rules: (fm) => fm.key("title").required(),
+ * });
+ * ```
+ */
+declare function defineConfig(config: FluoriteConfig): FluoriteConfig;
+/**
+ * Locate a config file: an explicit path, or the first conventional name found
+ * in `cwd`. Returns `undefined` when none is found.
+ */
+declare function resolveConfigPath(explicit: string | undefined, cwd?: string): Promise<string | undefined>;
+/** Dynamically import a config file and return its default export. */
+declare function loadConfig(path: string): Promise<FluoriteConfig>;
+
+/** Outcome of parsing frontmatter out of a Markdown source string. */
+interface ParseResult {
+    /** Parsed frontmatter data (empty object when none / on error). */
+    data: Record<string, unknown>;
+    /** The Markdown body following the frontmatter block. */
+    content: string;
+    /** Whether a frontmatter block was present at all. */
+    hasFrontmatter: boolean;
+    /** Parse error message, if the frontmatter (YAML) was malformed. */
+    error?: string;
+}
+/**
+ * Extract frontmatter from a Markdown source string.
+ *
+ * Never throws: malformed YAML is reported via the `error` field so callers
+ * can record it as a failure rather than crash.
+ */
+declare function parseFrontmatter(source: string): ParseResult;
+
+/** A check result paired with the file it came from. */
+interface FileReport {
+    file: string;
+    result: CheckResult;
+}
+interface FormatOptions {
+    /** Suppress per-file lines for passing files. */
+    quiet?: boolean;
+}
+/** Format file reports into a human-readable, colorized string. */
+declare function formatReports(reports: FileReport[], options?: FormatOptions): string;
+
+export { type CheckResult, EachAssertion, type FileReport, type FluoriteConfig, type FormatOptions, KeyAssertion, type ParseResult, Recorder, type RuleResult, type RulesFn, type ValueType, check, checkData, defineConfig, formatReports, loadConfig, parseFrontmatter, resolveConfigPath };

package/dist/index.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Fluent, chainable assertions for a single frontmatter key.
+ *
+ * Each terminal matcher records one {@link RuleResult} on the parent
+ * {@link Recorder} and returns `this`, so matchers can be chained:
+ *
+ * ```ts
+ * fm.key("title").required().type("string").lengthMin(10);
+ * fm.key("tags").not.has("ng");
+ * ```
+ *
+ * The `.not` modifier negates only the next matcher, then resets.
+ */
+declare class KeyAssertion {
+    #private;
+    private readonly recorder;
+    private readonly key;
+    private readonly value;
+    private readonly present;
+    constructor(recorder: Recorder, key: string, value: unknown, present: boolean);
+    /** Negate the next matcher in the chain. */
+    get not(): this;
+    /** The raw value (resolved against the sentinel) used by matchers. */
+    private get resolved();
+    /**
+     * Record a result, applying the pending `.not` negation, then reset it.
+     */
+    private record;
+    /** Assert the key exists in the frontmatter. */
+    required(): this;
+    /** Alias of {@link required}. */
+    exists(): this;
+    /** Assert the value is of the given type. */
+    type(expected: ValueType): this;
+    /** Assert the value strictly equals `expected` (deep for arrays/objects). */
+    eq(expected: unknown): this;
+    /**
+     * Assert the value is an array whose every element is in `allowed` (enum).
+     *
+     * Designed for catching tag notation drift: define the canonical set once
+     * and any stray / mistyped value is reported.
+     *
+     * ```ts
+     * fm.key("tags").subsetOf(["ok", "release", "blog"]);
+     * ```
+     */
+    subsetOf(allowed: readonly unknown[]): this;
+    /** Alias of {@link subsetOf}. */
+    only(allowed: readonly unknown[]): this;
+    /**
+     * Apply matchers to every element of an array value.
+     *
+     * ```ts
+     * fm.key("tags").each.oneOf(["ok", "release"]);
+     * fm.key("tags").each.matches(/^[a-z0-9-]+$/);
+     * ```
+     */
+    get each(): EachAssertion;
+    /** Assert the value is one of `allowed` (enum). */
+    oneOf(allowed: readonly unknown[]): this;
+    /** Assert a string value matches the given regular expression. */
+    matches(pattern: RegExp): this;
+    /** Assert an array contains `item`, or a string contains the substring. */
+    has(item: unknown): this;
+    /** Assert an array/string contains all of `items`. */
+    hasAll(items: readonly unknown[]): this;
+    /** Assert an array/string contains at least one of `items`. */
+    hasAny(items: readonly unknown[]): this;
+    /** Assert the string/array length equals `n`. */
+    length(n: number): this;
+    /** Assert the string/array length is at least `n`. */
+    lengthMin(n: number): this;
+    /** Assert the string/array length is at most `n`. */
+    lengthMax(n: number): this;
+}
+/**
+ * Applies matchers to every element of an array frontmatter value.
+ *
+ * Obtained via {@link KeyAssertion.each}. Each terminal matcher records a
+ * single {@link RuleResult}: it passes only when the value is an array and
+ * every element satisfies the matcher; failures list the offending elements.
+ */
+declare class EachAssertion {
+    #private;
+    private readonly recorder;
+    private readonly key;
+    private readonly value;
+    constructor(recorder: Recorder, key: string, value: unknown, negated: boolean);
+    /** Negate the next matcher in the chain. */
+    get not(): this;
+    private record;
+    /** Every element must be one of `allowed` (enum over array contents). */
+    oneOf(allowed: readonly unknown[]): this;
+    /** Every element must be of the given type. */
+    type(expected: ValueType): this;
+    /** Every (string) element must match the pattern. */
+    matches(pattern: RegExp): this;
+}
+
+/**
+ * The `fm` object passed to a rule set. Holds the parsed frontmatter data,
+ * hands out {@link KeyAssertion} instances via {@link key}, and accumulates
+ * every {@link RuleResult} the matchers record.
+ */
+declare class Recorder {
+    readonly data: Record<string, unknown>;
+    readonly results: RuleResult[];
+    constructor(data: Record<string, unknown>);
+    /** Begin a chain of assertions against the given frontmatter key. */
+    key(name: string): KeyAssertion;
+    /** Internal: append a recorded rule result. */
+    push(result: RuleResult): void;
+}
+
+/** The set of value types understood by the `type()` matcher. */
+type ValueType = "string" | "number" | "boolean" | "array" | "object" | "null";
+/** Result of a single matcher invocation against one key. */
+interface RuleResult {
+    /** The frontmatter key that was inspected, e.g. `"tags"`. */
+    key: string;
+    /** The matcher name, e.g. `"has"` or `"lengthMin"`. */
+    rule: string;
+    /** Whether the check passed. */
+    ok: boolean;
+    /** Whether the matcher was reached through `.not`. */
+    negated: boolean;
+    /** Human readable description of the outcome. */
+    message: string;
+    /** The actual value found at `key`. */
+    value: unknown;
+    /** The expected value / argument passed to the matcher, if any. */
+    expected?: unknown;
+}
+/** Aggregated outcome of running a rule set against one frontmatter object. */
+interface CheckResult {
+    /** True when every recorded rule passed. */
+    ok: boolean;
+    /** Every rule result, in the order they were recorded. */
+    results: RuleResult[];
+    /** Only the failing rule results. */
+    failures: RuleResult[];
+    /** The parsed frontmatter data. */
+    data: Record<string, unknown>;
+}
+/** A rule set: receives the recorder (`fm`) and registers matchers. */
+type RulesFn = (fm: Recorder) => void;
+/** Configuration accepted by `defineConfig` / consumed by the CLI. */
+interface FluoriteConfig {
+    /** Glob patterns of Markdown files to check. */
+    include?: string[];
+    /** Glob patterns to exclude. */
+    exclude?: string[];
+    /** The rule set applied to every file's frontmatter. */
+    rules: RulesFn;
+}
+
+/**
+ * Run a rule set against the frontmatter of a Markdown source string.
+ *
+ * Never throws: malformed YAML or a missing frontmatter block is surfaced as a
+ * failing {@link RuleResult} so results can always be collected and reported.
+ *
+ * ```ts
+ * const result = check(markdown, (fm) => {
+ *   fm.key("title").required().lengthMin(10);
+ *   fm.key("tags").not.has("ng");
+ * });
+ * if (!result.ok) console.error(result.failures);
+ * ```
+ */
+declare function check(source: string, rules: RulesFn): CheckResult;
+/** Run a rule set against already-parsed frontmatter data. */
+declare function checkData(data: Record<string, unknown>, rules: RulesFn): CheckResult;
+
+/**
+ * Identity helper for authoring a config file with full type inference:
+ *
+ * ```ts
+ * import { defineConfig } from "fluorite";
+ * export default defineConfig({
+ *   include: ["docs/**\/*.md"],
+ *   rules: (fm) => fm.key("title").required(),
+ * });
+ * ```
+ */
+declare function defineConfig(config: FluoriteConfig): FluoriteConfig;
+/**
+ * Locate a config file: an explicit path, or the first conventional name found
+ * in `cwd`. Returns `undefined` when none is found.
+ */
+declare function resolveConfigPath(explicit: string | undefined, cwd?: string): Promise<string | undefined>;
+/** Dynamically import a config file and return its default export. */
+declare function loadConfig(path: string): Promise<FluoriteConfig>;
+
+/** Outcome of parsing frontmatter out of a Markdown source string. */
+interface ParseResult {
+    /** Parsed frontmatter data (empty object when none / on error). */
+    data: Record<string, unknown>;
+    /** The Markdown body following the frontmatter block. */
+    content: string;
+    /** Whether a frontmatter block was present at all. */
+    hasFrontmatter: boolean;
+    /** Parse error message, if the frontmatter (YAML) was malformed. */
+    error?: string;
+}
+/**
+ * Extract frontmatter from a Markdown source string.
+ *
+ * Never throws: malformed YAML is reported via the `error` field so callers
+ * can record it as a failure rather than crash.
+ */
+declare function parseFrontmatter(source: string): ParseResult;
+
+/** A check result paired with the file it came from. */
+interface FileReport {
+    file: string;
+    result: CheckResult;
+}
+interface FormatOptions {
+    /** Suppress per-file lines for passing files. */
+    quiet?: boolean;
+}
+/** Format file reports into a human-readable, colorized string. */
+declare function formatReports(reports: FileReport[], options?: FormatOptions): string;
+
+export { type CheckResult, EachAssertion, type FileReport, type FluoriteConfig, type FormatOptions, KeyAssertion, type ParseResult, Recorder, type RuleResult, type RulesFn, type ValueType, check, checkData, defineConfig, formatReports, loadConfig, parseFrontmatter, resolveConfigPath };

package/dist/index.js

@@ -0,0 +1,25 @@
+import {
+  EachAssertion,
+  KeyAssertion,
+  Recorder,
+  check,
+  checkData,
+  defineConfig,
+  formatReports,
+  loadConfig,
+  parseFrontmatter,
+  resolveConfigPath
+} from "./chunk-2QW4LSG5.js";
+export {
+  EachAssertion,
+  KeyAssertion,
+  Recorder,
+  check,
+  checkData,
+  defineConfig,
+  formatReports,
+  loadConfig,
+  parseFrontmatter,
+  resolveConfigPath
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@yukyu30/fluorite",
+  "version": "0.1.0",
+  "description": "Inspect and validate Markdown frontmatter with a readable, chainable DSL — usable as a library and a CLI.",
+  "type": "module",
+  "license": "MIT",
+  "author": "yukyu30",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yukyu30/fluorite.git"
+  },
+  "keywords": [
+    "frontmatter",
+    "markdown",
+    "yaml",
+    "validation",
+    "linter",
+    "cli"
+  ],
+  "bin": {
+    "fluorite": "./dist/cli.js"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "picocolors": "^1.1.1",
+    "tinyglobby": "^0.2.10"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}