@yukyu30/fluorite 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yukyu30
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,209 @@
+# fluorite
+
+Inspect and validate Markdown **frontmatter** with a readable, chainable DSL —
+usable as a **library** and a **CLI**.
+
+```md
+---
+tags: ["ok", "ng"]
+title: "これはタイトルです"
+---
+```
+
+```ts
+import { check } from "@yukyu30/fluorite";
+
+const result = check(markdown, (fm) => {
+  fm.key("title").required().type("string").lengthMin(10);
+  fm.key("tags").not.has("ng"); // ← fails (red) because "ng" is present
+});
+
+result.ok; // false
+result.failures; // [{ key: "tags", rule: "has", negated: true, ok: false, ... }]
+```
+
+Checks never throw — every rule produces a **result object** (pass/fail with a
+reason) so you can collect and report them as red/green.
+
+## Install
+
+```sh
+npm install @yukyu30/fluorite
+```
+
+## Library API
+
+### `check(source, rules) => CheckResult`
+
+Parses the frontmatter out of a Markdown `source` string and runs the `rules`
+callback against it. The `fm` argument is a recorder: each matcher you call
+records one result.
+
+```ts
+const result = check(source, (fm) => {
+  fm.key("title").required().lengthMin(10);
+});
+```
+
+`CheckResult`:
+
+| field      | description                                  |
+| ---------- | -------------------------------------------- |
+| `ok`       | `true` when every rule passed                |
+| `results`  | every recorded `RuleResult`, in order        |
+| `failures` | only the failing `RuleResult`s               |
+| `data`     | the parsed frontmatter object                |
+
+A missing frontmatter block or malformed YAML is recorded as a failing
+`parse` rule rather than throwing.
+
+### `checkData(data, rules) => CheckResult`
+
+Same as `check`, but runs against an already-parsed frontmatter object.
+
+### Matchers
+
+Begin a chain with `fm.key("name")`. The `.not` modifier negates **only the
+next** matcher, then resets.
+
+**Existence / type**
+
+- `required()` / `exists()` — the key is present
+- `type(t)` — `"string" | "number" | "boolean" | "array" | "object" | "null"`
+
+**Value**
+
+- `eq(value)` — deep-equality
+- `oneOf([...])` — value is one of the allowed set (enum)
+- `matches(regexp)` — string matches the pattern
+
+**Containment (arrays & strings)**
+
+- `has(value)` — array contains the element, or string contains the substring
+- `hasAll([...])` — contains every item
+- `hasAny([...])` — contains at least one item
+
+**Enum / array contents** — catch tag notation drift
+
+- `subsetOf([...])` / `only([...])` — value is an array whose every element is
+  in the allowed set; failures list the offending (typo'd) values
+- `each.oneOf([...])` — same as `subsetOf`, via the per-element accessor
+- `each.type(t)` — every element is of type `t`
+- `each.matches(regexp)` — every (string) element matches the pattern
+
+**Length (arrays & strings)**
+
+- `length(n)` — length equals `n`
+- `lengthMin(n)` — length `>= n`
+- `lengthMax(n)` — length `<= n`
+
+```ts
+check(source, (fm) => {
+  fm.key("status").oneOf(["draft", "published"]);
+  fm.key("slug").matches(/^[a-z0-9-]+$/);
+  fm.key("tags").type("array").hasAll(["blog"]).not.has("ng");
+  fm.key("summary").lengthMin(20).lengthMax(160);
+});
+```
+
+### Defining a tag enum
+
+Tags drift easily (`Blog` vs `blog`, stray `ng`). Define the canonical
+vocabulary once and `subsetOf` flags anything outside it — the failure names
+the exact offending values:
+
+```ts
+const TAGS = ["ok", "release", "blog", "news"];
+
+check(source, (fm) => {
+  fm.key("tags").type("array").subsetOf(TAGS);
+});
+// tags: ["ok", "Blog", "ng"]
+// → all items should be one of [...] (invalid: ["Blog","ng"])
+
+// Or enforce a notation rule instead of a fixed list:
+check(source, (fm) => {
+  fm.key("tags").each.matches(/^[a-z0-9-]+$/); // lowercase kebab-case only
+});
+```
+
+## CLI
+
+```sh
+fluorite check "docs/**/*.md" [--config <path>] [--quiet]
+```
+
+- Collects files via glob, checks each file's frontmatter, prints a red/green
+  report, and exits with code `1` if any file fails (great for CI).
+- Rules come from a config file (`fluorite.config.{js,mjs,cjs}`, or `--config`).
+
+```
+✘ docs/bad.md
+  ✘ title: length should be >= 10 (was 2) (value: "短い")
+  ✘ tags: should not have "ng" (value: ["ok","ng"])
+✔ docs/good.md
+
+2 files, 1 passed, 1 failed, 2 rule failures
+```
+
+Options:
+
+- `-c, --config <path>` — path to a config file
+- `-q, --quiet` — only print files that have failures
+- `-h, --help` — show help
+
+### Config file
+
+```js
+// fluorite.config.mjs
+import { defineConfig } from "@yukyu30/fluorite";
+
+export default defineConfig({
+  include: ["docs/**/*.md"],
+  exclude: ["**/node_modules/**"],
+  rules: (fm) => {
+    fm.key("title").required().type("string").lengthMin(10);
+    fm.key("tags").required().type("array").not.has("ng");
+  },
+});
+```
+
+Positional patterns on the CLI override `include`. If neither is given,
+`**/*.md` is used.
+
+## Releasing
+
+Releases are automated with [tagpr](https://github.com/Songmu/tagpr) +
+`npm publish` (`.github/workflows/tagpr.yml`):
+
+1. Push commits to `main`. tagpr opens/updates a **Release PR** that bumps the
+   version in `package.json` and updates `CHANGELOG.md`.
+2. Label the Release PR `minor` / `major` to control the bump (default: patch).
+3. Merge the Release PR. tagpr creates the `vX.Y.Z` tag + GitHub Release, and
+   the same workflow run publishes the package to npm.
+
+Publishing uses npm **trusted publishing (OIDC)** — no `NPM_TOKEN` secret, and
+provenance is attached automatically.
+
+One-time setup:
+
+1. **First publish** (the package must exist before a trusted publisher can be
+   attached). From your machine:
+   ```sh
+   npm login
+   npm publish --access public
+   ```
+2. On npmjs.com → the package → **Settings → Trusted Publisher → GitHub
+   Actions**, set:
+   - Organization or user: `yukyu30`
+   - Repository: `fluorite`
+   - Workflow filename: `tagpr.yml`
+   - Environment: *(leave empty)*
+3. GitHub → Settings → Actions → General → enable
+   "Allow GitHub Actions to create and approve pull requests" (for tagpr).
+
+After that, every merged Release PR publishes automatically with no token.
+
+## License
+
+MIT

package/dist/chunk-2QW4LSG5.js

@@ -0,0 +1,484 @@
+// src/parse.ts
+import matter from "gray-matter";
+function parseFrontmatter(source) {
+  const hasFrontmatter = /^?\s*---\r?\n/.test(source);
+  try {
+    const parsed = matter(source);
+    const data = parsed.data ?? {};
+    return {
+      data,
+      content: parsed.content,
+      hasFrontmatter
+    };
+  } catch (err) {
+    return {
+      data: {},
+      content: source,
+      hasFrontmatter,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+
+// src/assertion.ts
+var MISSING = /* @__PURE__ */ Symbol("missing");
+function valueType(value) {
+  if (value === MISSING) return "undefined";
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  const t = typeof value;
+  if (t === "string" || t === "number" || t === "boolean" || t === "object") {
+    return t;
+  }
+  return "undefined";
+}
+function lengthOf(value) {
+  if (typeof value === "string" || Array.isArray(value)) return value.length;
+  return void 0;
+}
+function display(value) {
+  if (value === MISSING) return "undefined";
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+var KeyAssertion = class {
+  constructor(recorder, key, value, present) {
+    this.recorder = recorder;
+    this.key = key;
+    this.value = value;
+    this.present = present;
+  }
+  recorder;
+  key;
+  value;
+  present;
+  #negated = false;
+  /** Negate the next matcher in the chain. */
+  get not() {
+    this.#negated = true;
+    return this;
+  }
+  /** The raw value (resolved against the sentinel) used by matchers. */
+  get resolved() {
+    return this.present ? this.value : MISSING;
+  }
+  /**
+   * Record a result, applying the pending `.not` negation, then reset it.
+   */
+  record(rule, rawPass, describe, expected) {
+    const negated = this.#negated;
+    this.#negated = false;
+    const ok = negated ? !rawPass : rawPass;
+    const result = {
+      key: this.key,
+      rule,
+      ok,
+      negated,
+      message: describe(negated),
+      value: this.present ? this.value : void 0,
+      expected
+    };
+    this.recorder.push(result);
+    return this;
+  }
+  /** Assert the key exists in the frontmatter. */
+  required() {
+    return this.record(
+      "required",
+      this.present,
+      (neg) => neg ? `should not exist` : `is required`
+    );
+  }
+  /** Alias of {@link required}. */
+  exists() {
+    return this.record(
+      "exists",
+      this.present,
+      (neg) => neg ? `should not exist` : `should exist`
+    );
+  }
+  /** Assert the value is of the given type. */
+  type(expected) {
+    const actual = valueType(this.resolved);
+    return this.record(
+      "type",
+      actual === expected,
+      (neg) => neg ? `should not be of type ${expected}` : `should be of type ${expected} (was ${actual})`,
+      expected
+    );
+  }
+  /** Assert the value strictly equals `expected` (deep for arrays/objects). */
+  eq(expected) {
+    return this.record(
+      "eq",
+      deepEqual(this.resolved, expected),
+      (neg) => neg ? `should not equal ${display(expected)}` : `should equal ${display(expected)}`,
+      expected
+    );
+  }
+  /**
+   * 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) {
+    const v = this.resolved;
+    const isArray = Array.isArray(v);
+    const invalid = isArray ? v.filter((el) => !allowed.some((a) => deepEqual(el, a))) : [];
+    return this.record(
+      "subsetOf",
+      isArray && invalid.length === 0,
+      (neg) => {
+        if (!isArray) return `should be an array of values from ${display(allowed)}`;
+        if (neg) return `should contain values outside ${display(allowed)}`;
+        return invalid.length ? `all items should be one of ${display(allowed)} (invalid: ${display(invalid)})` : `all items should be one of ${display(allowed)}`;
+      },
+      allowed
+    );
+  }
+  /** Alias of {@link subsetOf}. */
+  only(allowed) {
+    return this.subsetOf(allowed);
+  }
+  /**
+   * 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() {
+    const negated = this.#negated;
+    this.#negated = false;
+    return new EachAssertion(this.recorder, this.key, this.resolved, negated);
+  }
+  /** Assert the value is one of `allowed` (enum). */
+  oneOf(allowed) {
+    return this.record(
+      "oneOf",
+      allowed.some((a) => deepEqual(this.resolved, a)),
+      (neg) => neg ? `should not be one of ${display(allowed)}` : `should be one of ${display(allowed)}`,
+      allowed
+    );
+  }
+  /** Assert a string value matches the given regular expression. */
+  matches(pattern) {
+    const v = this.resolved;
+    const pass = typeof v === "string" && pattern.test(v);
+    return this.record(
+      "matches",
+      pass,
+      (neg) => neg ? `should not match ${pattern}` : `should match ${pattern}`,
+      pattern.source
+    );
+  }
+  /** Assert an array contains `item`, or a string contains the substring. */
+  has(item) {
+    const v = this.resolved;
+    let pass = false;
+    if (Array.isArray(v)) pass = v.some((el) => deepEqual(el, item));
+    else if (typeof v === "string" && typeof item === "string")
+      pass = v.includes(item);
+    return this.record(
+      "has",
+      pass,
+      (neg) => neg ? `should not have ${display(item)}` : `should have ${display(item)}`,
+      item
+    );
+  }
+  /** Assert an array/string contains all of `items`. */
+  hasAll(items) {
+    const v = this.resolved;
+    const pass = items.every((item) => contains(v, item));
+    return this.record(
+      "hasAll",
+      pass,
+      (neg) => neg ? `should not have all of ${display(items)}` : `should have all of ${display(items)}`,
+      items
+    );
+  }
+  /** Assert an array/string contains at least one of `items`. */
+  hasAny(items) {
+    const v = this.resolved;
+    const pass = items.some((item) => contains(v, item));
+    return this.record(
+      "hasAny",
+      pass,
+      (neg) => neg ? `should not have any of ${display(items)}` : `should have any of ${display(items)}`,
+      items
+    );
+  }
+  /** Assert the string/array length equals `n`. */
+  length(n) {
+    const len = lengthOf(this.resolved);
+    return this.record(
+      "length",
+      len === n,
+      (neg) => neg ? `length should not be ${n} (was ${len ?? "n/a"})` : `length should be ${n} (was ${len ?? "n/a"})`,
+      n
+    );
+  }
+  /** Assert the string/array length is at least `n`. */
+  lengthMin(n) {
+    const len = lengthOf(this.resolved);
+    return this.record(
+      "lengthMin",
+      len !== void 0 && len >= n,
+      (neg) => neg ? `length should be < ${n} (was ${len ?? "n/a"})` : `length should be >= ${n} (was ${len ?? "n/a"})`,
+      n
+    );
+  }
+  /** Assert the string/array length is at most `n`. */
+  lengthMax(n) {
+    const len = lengthOf(this.resolved);
+    return this.record(
+      "lengthMax",
+      len !== void 0 && len <= n,
+      (neg) => neg ? `length should be > ${n} (was ${len ?? "n/a"})` : `length should be <= ${n} (was ${len ?? "n/a"})`,
+      n
+    );
+  }
+};
+var EachAssertion = class {
+  constructor(recorder, key, value, negated) {
+    this.recorder = recorder;
+    this.key = key;
+    this.value = value;
+    this.#negated = negated;
+  }
+  recorder;
+  key;
+  value;
+  #negated;
+  /** Negate the next matcher in the chain. */
+  get not() {
+    this.#negated = true;
+    return this;
+  }
+  record(rule, perElement, describe, expected) {
+    const negated = this.#negated;
+    this.#negated = false;
+    const isArray = Array.isArray(this.value);
+    const invalid = isArray ? this.value.filter((el) => !perElement(el)) : [];
+    const rawPass = isArray && invalid.length === 0;
+    const ok = isArray ? negated ? !rawPass : rawPass : false;
+    this.recorder.push({
+      key: this.key,
+      rule: `each.${rule}`,
+      ok,
+      negated,
+      message: describe(negated, invalid, isArray),
+      value: this.value === MISSING ? void 0 : this.value,
+      expected
+    });
+    return this;
+  }
+  /** Every element must be one of `allowed` (enum over array contents). */
+  oneOf(allowed) {
+    return this.record(
+      "oneOf",
+      (el) => allowed.some((a) => deepEqual(el, a)),
+      (neg, invalid, isArray) => !isArray ? `should be an array of values from ${display(allowed)}` : neg ? `every item should be outside ${display(allowed)}` : `every item should be one of ${display(allowed)}${invalid.length ? ` (invalid: ${display(invalid)})` : ""}`,
+      allowed
+    );
+  }
+  /** Every element must be of the given type. */
+  type(expected) {
+    return this.record(
+      "type",
+      (el) => valueType(el) === expected,
+      (neg, invalid, isArray) => !isArray ? `should be an array of ${expected}` : neg ? `every item should not be of type ${expected}` : `every item should be of type ${expected}${invalid.length ? ` (invalid: ${display(invalid)})` : ""}`,
+      expected
+    );
+  }
+  /** Every (string) element must match the pattern. */
+  matches(pattern) {
+    return this.record(
+      "matches",
+      (el) => typeof el === "string" && pattern.test(el),
+      (neg, invalid, isArray) => !isArray ? `should be an array of strings matching ${pattern}` : neg ? `every item should not match ${pattern}` : `every item should match ${pattern}${invalid.length ? ` (invalid: ${display(invalid)})` : ""}`,
+      pattern.source
+    );
+  }
+};
+function contains(container, item) {
+  if (Array.isArray(container)) return container.some((el) => deepEqual(el, item));
+  if (typeof container === "string" && typeof item === "string")
+    return container.includes(item);
+  return false;
+}
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== "object" || typeof b !== "object") return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    return a.every((el, i) => deepEqual(el, b[i]));
+  }
+  const ao = a;
+  const bo = b;
+  const ak = Object.keys(ao);
+  const bk = Object.keys(bo);
+  if (ak.length !== bk.length) return false;
+  return ak.every((k) => deepEqual(ao[k], bo[k]));
+}
+
+// src/recorder.ts
+var Recorder = class {
+  constructor(data) {
+    this.data = data;
+  }
+  data;
+  results = [];
+  /** Begin a chain of assertions against the given frontmatter key. */
+  key(name) {
+    const present = Object.prototype.hasOwnProperty.call(this.data, name);
+    return new KeyAssertion(this, name, this.data[name], present);
+  }
+  /** Internal: append a recorded rule result. */
+  push(result) {
+    this.results.push(result);
+  }
+};
+
+// src/check.ts
+function check(source, rules) {
+  const parsed = parseFrontmatter(source);
+  const recorder = new Recorder(parsed.data);
+  if (parsed.error) {
+    recorder.push(parseErrorResult(`invalid frontmatter: ${parsed.error}`));
+  } else if (!parsed.hasFrontmatter) {
+    recorder.push(parseErrorResult("no frontmatter block found"));
+  } else {
+    rules(recorder);
+  }
+  const results = recorder.results;
+  const failures = results.filter((r) => !r.ok);
+  return {
+    ok: failures.length === 0,
+    results,
+    failures,
+    data: parsed.data
+  };
+}
+function checkData(data, rules) {
+  const recorder = new Recorder(data);
+  rules(recorder);
+  const results = recorder.results;
+  const failures = results.filter((r) => !r.ok);
+  return { ok: failures.length === 0, results, failures, data };
+}
+function parseErrorResult(message) {
+  return {
+    key: "(frontmatter)",
+    rule: "parse",
+    ok: false,
+    negated: false,
+    message,
+    value: void 0
+  };
+}
+
+// src/config.ts
+import { pathToFileURL } from "url";
+import { access } from "fs/promises";
+import { resolve } from "path";
+function defineConfig(config) {
+  return config;
+}
+var CONFIG_NAMES = [
+  "fluorite.config.js",
+  "fluorite.config.mjs",
+  "fluorite.config.cjs"
+];
+async function resolveConfigPath(explicit, cwd = process.cwd()) {
+  if (explicit) return resolve(cwd, explicit);
+  for (const name of CONFIG_NAMES) {
+    const candidate = resolve(cwd, name);
+    if (await fileExists(candidate)) return candidate;
+  }
+  return void 0;
+}
+async function loadConfig(path) {
+  const mod = await import(pathToFileURL(path).href);
+  const config = mod.default ?? mod;
+  if (!config || typeof config.rules !== "function") {
+    throw new Error(
+      `Config at ${path} must export a default object with a "rules" function.`
+    );
+  }
+  return config;
+}
+async function fileExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/report.ts
+import pc from "picocolors";
+function displayValue(value) {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+function formatReports(reports, options = {}) {
+  const lines = [];
+  let passed = 0;
+  let failed = 0;
+  let ruleFailures = 0;
+  for (const { file, result } of reports) {
+    if (result.ok) {
+      passed++;
+      if (!options.quiet) lines.push(`${pc.green("\u2714")} ${file}`);
+    } else {
+      failed++;
+      lines.push(`${pc.red("\u2718")} ${file}`);
+      for (const failure of result.failures) {
+        ruleFailures++;
+        const where = pc.dim(`(value: ${displayValue(failure.value)})`);
+        lines.push(
+          `  ${pc.red("\u2718")} ${pc.bold(failure.key)}: ${failure.message} ${where}`
+        );
+      }
+    }
+  }
+  const summary = [
+    `${reports.length} files`,
+    pc.green(`${passed} passed`),
+    failed > 0 ? pc.red(`${failed} failed`) : `${failed} failed`,
+    `${ruleFailures} rule failures`
+  ].join(", ");
+  lines.push("");
+  lines.push(summary);
+  return lines.join("\n");
+}
+
+export {
+  parseFrontmatter,
+  KeyAssertion,
+  EachAssertion,
+  Recorder,
+  check,
+  checkData,
+  defineConfig,
+  resolveConfigPath,
+  loadConfig,
+  formatReports
+};
+//# sourceMappingURL=chunk-2QW4LSG5.js.map