driftfence 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DriftFence contributors
+
+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,119 @@
+# DriftFence
+
+[![CI](https://github.com/CHAPAPOPA/driftfence/actions/workflows/ci.yml/badge.svg)](https://github.com/CHAPAPOPA/driftfence/actions/workflows/ci.yml)
+
+Make sure your README doesn't lie.
+
+DriftFence is a TypeScript Node.js CLI that catches outdated README and docs commands, package scripts, file references, and env var references before they reach users.
+
+## Install
+
+Once published to npm:
+
+```sh
+npm install -D driftfence
+```
+
+## Usage
+
+Check the current project:
+
+```sh
+npx driftfence check
+```
+
+Check a specific project directory:
+
+```sh
+npx driftfence check ./path/to/project
+```
+
+## Example Output
+
+The local clean demo exits with code 0:
+
+```sh
+npm run demo:clean
+```
+
+The local drift demo intentionally contains documentation drift and exits with code 1:
+
+```sh
+npm run demo:drift
+```
+
+Example output from the drift fixture:
+
+```text
+DriftFence found documentation drift.
+
+Package scripts:
+- `npm run build` in README.md references missing package.json script `build`.
+
+File paths:
+- `docs/missing.md` referenced in README.md does not exist.
+- `docs/advanced.md` referenced in docs/config.md does not exist.
+
+Env vars:
+- `DATABASE_URL` is used in src/index.ts but missing from .env.example.
+
+4 issues found.
+```
+
+## MVP Checks
+
+DriftFence checks `README.md` and `docs/**/*.md` for documentation drift.
+
+Current checks:
+
+- package script references
+- file path references
+- env var references in Markdown docs
+- env var usage in source files
+
+Package script references include commands like:
+
+```sh
+npm run build
+npm test
+npm start
+pnpm build
+yarn build
+```
+
+Env var checks currently support references like:
+
+```text
+API_URL
+DATABASE_URL
+VITE_API_URL
+```
+
+and source usages like:
+
+```ts
+process.env.API_URL
+import.meta.env.VITE_API_URL
+```
+
+## Exit Codes
+
+DriftFence uses stable CLI exit codes:
+
+- `0` — no documentation drift found
+- `1` — documentation drift found
+- `2` — invalid project directory or CLI usage error
+
+## Roadmap
+
+- MDX docs
+- GitHub Action
+- changed-files mode
+- configurable ignore rules
+- richer source analysis
+
+## AI
+
+AI features are not included in the MVP.
+
+DriftFence is deterministic-first: it checks concrete references in docs and code instead of guessing.

package/dist/chunk-4RCBAET6.js

@@ -0,0 +1,576 @@
+// src/checkers/packageScripts.ts
+import { readFile } from "fs/promises";
+import { join } from "path";
+var npmScriptPattern = /\bnpm\s+(?:run\s+([A-Za-z0-9:_-]+)|(start|test))\b/g;
+var shorthandScriptPattern = /\b(pnpm|yarn)\s+(?:run\s+)?([A-Za-z0-9:_-]+)\b/g;
+var packageManagerCommands = /* @__PURE__ */ new Set([
+  "add",
+  "audit",
+  "bin",
+  "cache",
+  "ci",
+  "config",
+  "create",
+  "dedupe",
+  "dlx",
+  "doctor",
+  "exec",
+  "explain",
+  "global",
+  "help",
+  "import",
+  "init",
+  "install",
+  "link",
+  "list",
+  "login",
+  "logout",
+  "node",
+  "outdated",
+  "pack",
+  "patch",
+  "plugin",
+  "publish",
+  "rebuild",
+  "remove",
+  "root",
+  "run",
+  "search",
+  "set",
+  "setup",
+  "store",
+  "uninstall",
+  "unlink",
+  "update",
+  "upgrade",
+  "view",
+  "why",
+  "workspace",
+  "workspaces"
+]);
+async function checkPackageScripts(projectRoot, references) {
+  const scriptReferences = findPackageScriptReferences(references);
+  if (scriptReferences.length === 0) {
+    return [];
+  }
+  const packageJsonResult = await readPackageJson(projectRoot);
+  if ("issue" in packageJsonResult) {
+    return [packageJsonResult.issue];
+  }
+  const scripts = packageJsonResult.packageJson.scripts ?? {};
+  return scriptReferences.filter((reference) => !hasOwn(scripts, reference.script)).map((reference) => ({
+    type: "package-script",
+    path: reference.path,
+    command: reference.command,
+    script: reference.script
+  }));
+}
+function findPackageScriptReferences(references) {
+  const scriptReferences = [];
+  for (const reference of references) {
+    scriptReferences.push(...findNpmScriptReferences(reference.value, reference.path));
+    scriptReferences.push(
+      ...findShorthandScriptReferences(reference.value, reference.path)
+    );
+  }
+  return uniqueScriptReferences(scriptReferences);
+}
+function findNpmScriptReferences(text, path) {
+  const references = [];
+  for (const match of text.matchAll(npmScriptPattern)) {
+    const npmRunScript = match[1];
+    const npmTestScript = match[2];
+    const script = npmRunScript ?? npmTestScript;
+    if (!script) {
+      continue;
+    }
+    references.push({
+      path,
+      command: normalizeCommand(match[0]),
+      packageManager: "npm",
+      script
+    });
+  }
+  return references;
+}
+function findShorthandScriptReferences(text, path) {
+  const references = [];
+  for (const match of text.matchAll(shorthandScriptPattern)) {
+    const packageManager = match[1];
+    const script = match[2];
+    if (packageManager !== "pnpm" && packageManager !== "yarn" || !script || packageManagerCommands.has(script)) {
+      continue;
+    }
+    references.push({
+      path,
+      command: normalizeCommand(match[0]),
+      packageManager,
+      script
+    });
+  }
+  return references;
+}
+async function readPackageJson(projectRoot) {
+  const path = "package.json";
+  const packageJsonPath = join(projectRoot, path);
+  let rawPackageJson;
+  try {
+    rawPackageJson = await readFile(packageJsonPath, "utf8");
+  } catch (error) {
+    return {
+      issue: {
+        type: "package-json",
+        path,
+        message: getErrorCode(error) === "ENOENT" ? "package.json was not found." : `package.json could not be read: ${getErrorMessage(error)}`
+      }
+    };
+  }
+  try {
+    return { packageJson: JSON.parse(rawPackageJson) };
+  } catch (error) {
+    return {
+      issue: {
+        type: "package-json",
+        path,
+        message: `package.json is not valid JSON: ${getErrorMessage(error)}`
+      }
+    };
+  }
+}
+function uniqueScriptReferences(references) {
+  const seen = /* @__PURE__ */ new Set();
+  const uniqueReferences = [];
+  for (const reference of references) {
+    const key = `${reference.path}:${reference.packageManager}:${reference.command}:${reference.script}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    uniqueReferences.push(reference);
+  }
+  return uniqueReferences;
+}
+function normalizeCommand(command) {
+  return command.replace(/\s+/g, " ").trim();
+}
+function hasOwn(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key);
+}
+function getErrorCode(error) {
+  return typeof error === "object" && error !== null && "code" in error ? String(error.code) : void 0;
+}
+function getErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/checkers/filePaths.ts
+import { access } from "fs/promises";
+import { resolve } from "path";
+var pathTokenPattern = /(?:^|[\s"'`(])((?:\.{1,2}[\\/][^\s"'`()<>[\]{}]+|[A-Za-z0-9_.-]+[\\/][^\s"'`()<>[\]{}]+|\.[A-Za-z0-9_-][A-Za-z0-9_.-]*|[A-Za-z0-9_-]+\.[A-Za-z][A-Za-z0-9]{1,7})(?:[?#][A-Za-z0-9_.:/#?=&-]+)?)/g;
+async function checkFilePaths(projectRoot, references) {
+  const pathReferences = findFilePathReferences(references);
+  const issues = [];
+  for (const reference of pathReferences) {
+    const absolutePath = resolve(projectRoot, reference.path);
+    try {
+      await access(absolutePath);
+    } catch {
+      issues.push({
+        type: "file-path",
+        path: reference.path,
+        markdownPath: reference.markdownPath
+      });
+    }
+  }
+  return issues;
+}
+function findFilePathReferences(references) {
+  const pathReferences = [];
+  for (const reference of references) {
+    pathReferences.push(
+      ...findFilePathReferencesInText(reference.value, reference.path)
+    );
+  }
+  return uniquePathReferences(pathReferences);
+}
+function findFilePathReferencesInText(text, markdownPath) {
+  const references = [];
+  for (const match of text.matchAll(pathTokenPattern)) {
+    const path = cleanPathCandidate(match[1]);
+    if (!isLikelyFilePath(path)) {
+      continue;
+    }
+    references.push({ path, markdownPath });
+  }
+  return references;
+}
+function cleanPathCandidate(candidate) {
+  const path = (candidate ?? "").trim().replace(/^[`'"]+|[`'"]+$/g, "").replace(/[),.;:!?]+$/g, "").replace(/\\/g, "/");
+  const withoutUrlSuffix = path.split(/[?#]/)[0] ?? "";
+  return withoutUrlSuffix.replace(/:\d+(?::\d+)?$/g, "").replace(/^\.\//, "");
+}
+function isLikelyFilePath(path) {
+  if (path.length === 0 || path.startsWith("@") || path.startsWith("-") || path.includes("://") || path.includes("*") || path.includes("$")) {
+    return false;
+  }
+  if (!path.includes("/") && /^[A-Z][a-z]+(?:\.[a-z0-9]+)+$/.test(path)) {
+    return false;
+  }
+  return path.includes("/") || path.startsWith(".") || hasExtension(path);
+}
+function hasExtension(path) {
+  return /(^|[/\\])[^/\\]+\.[A-Za-z][A-Za-z0-9]{1,7}$/.test(path);
+}
+function uniquePathReferences(references) {
+  const seen = /* @__PURE__ */ new Set();
+  const uniqueReferences = [];
+  for (const reference of references) {
+    const key = `${reference.markdownPath}:${reference.path}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    uniqueReferences.push(reference);
+  }
+  return uniqueReferences;
+}
+
+// src/checkers/envVars.ts
+import { readFile as readFile2, readdir } from "fs/promises";
+import { join as join2, relative } from "path";
+var envVarPattern = /\b[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+\b/g;
+var processEnvPattern = /\bprocess\.env\.([A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+)\b/g;
+var importMetaEnvPattern = /\bimport\.meta\.env\.([A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+)\b/g;
+var sourceExtensions = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
+async function checkEnvVars(projectRoot, markdownDocuments) {
+  const envExampleNames = await readEnvExampleNames(projectRoot);
+  const references = [
+    ...markdownDocuments.flatMap(
+      (document) => findMarkdownEnvVarReferences(document)
+    ),
+    ...await findSourceEnvVarReferences(projectRoot)
+  ];
+  return references.filter((reference) => !envExampleNames.has(reference.name)).map((reference) => ({
+    type: "env-var",
+    name: reference.name,
+    source: reference.source,
+    path: reference.path
+  }));
+}
+function findEnvExampleNames(content) {
+  const names = /* @__PURE__ */ new Set();
+  for (const line of content.split(/\r?\n/)) {
+    const trimmedLine = line.trim();
+    if (trimmedLine.length === 0 || trimmedLine.startsWith("#")) {
+      continue;
+    }
+    const match = /^([A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+)\s*=/.exec(trimmedLine);
+    if (match?.[1]) {
+      names.add(match[1]);
+    }
+  }
+  return names;
+}
+function findMarkdownEnvVarReferences(document) {
+  return uniqueEnvVarReferences(
+    [...document.content.matchAll(envVarPattern)].map((match) => ({
+      name: match[0],
+      source: "markdown",
+      path: document.path
+    }))
+  );
+}
+async function readEnvExampleNames(projectRoot) {
+  try {
+    return findEnvExampleNames(
+      await readFile2(join2(projectRoot, ".env.example"), "utf8")
+    );
+  } catch (error) {
+    if (getErrorCode2(error) === "ENOENT") {
+      return /* @__PURE__ */ new Set();
+    }
+    throw error;
+  }
+}
+async function findSourceEnvVarReferences(projectRoot) {
+  const sourceRoot = join2(projectRoot, "src");
+  const sourceFiles = await findSourceFiles(sourceRoot);
+  const references = [];
+  for (const sourceFile of sourceFiles) {
+    const content = await readFile2(sourceFile, "utf8");
+    const path = normalizePath(relative(projectRoot, sourceFile));
+    references.push(
+      ...findSourceEnvVarReferencesInText(content).map((reference) => ({
+        ...reference,
+        path
+      }))
+    );
+  }
+  return uniqueEnvVarReferences(references);
+}
+function findSourceEnvVarReferencesInText(content) {
+  const references = [];
+  for (const match of content.matchAll(processEnvPattern)) {
+    if (match[1]) {
+      references.push({ name: match[1], source: "source", path: "" });
+    }
+  }
+  for (const match of content.matchAll(importMetaEnvPattern)) {
+    if (match[1]) {
+      references.push({ name: match[1], source: "source", path: "" });
+    }
+  }
+  return references;
+}
+async function findSourceFiles(directory) {
+  let entries;
+  try {
+    entries = await readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    if (getErrorCode2(error) === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+  const files = [];
+  for (const entry of entries) {
+    const path = join2(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await findSourceFiles(path));
+      continue;
+    }
+    if (entry.isFile() && sourceExtensions.has(getExtension(entry.name))) {
+      files.push(path);
+    }
+  }
+  return files;
+}
+function uniqueEnvVarReferences(references) {
+  const seen = /* @__PURE__ */ new Set();
+  const uniqueReferences = [];
+  for (const reference of references) {
+    const key = `${reference.source}:${reference.path}:${reference.name}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    uniqueReferences.push(reference);
+  }
+  return uniqueReferences;
+}
+function getExtension(path) {
+  const index = path.lastIndexOf(".");
+  return index === -1 ? "" : path.slice(index);
+}
+function normalizePath(path) {
+  return path.replace(/\\/g, "/");
+}
+function getErrorCode2(error) {
+  return typeof error === "object" && error !== null && "code" in error ? String(error.code) : void 0;
+}
+
+// src/markdown/extractMarkdownText.ts
+import remarkParse from "remark-parse";
+import { unified } from "unified";
+function extractMarkdownText(markdown) {
+  const tree = unified().use(remarkParse).parse(markdown);
+  const references = [];
+  collectMarkdownText(tree, references);
+  return references;
+}
+function collectMarkdownText(node, references) {
+  if ((node.type === "code" || node.type === "inlineCode") && typeof node.value === "string") {
+    references.push({ kind: node.type, value: node.value });
+  }
+  if (!Array.isArray(node.children)) {
+    return;
+  }
+  for (const child of node.children) {
+    collectMarkdownText(child, references);
+  }
+}
+
+// src/markdown/readMarkdownDocuments.ts
+import { readFile as readFile3, readdir as readdir2 } from "fs/promises";
+import { join as join3, relative as relative2 } from "path";
+async function readMarkdownDocuments(projectRoot) {
+  const paths = await findMarkdownPaths(projectRoot);
+  const documents = [];
+  for (const path of paths) {
+    const content = await readFile3(join3(projectRoot, path), "utf8");
+    documents.push({
+      path,
+      content,
+      references: extractMarkdownText(content).map((reference) => ({
+        ...reference,
+        path
+      }))
+    });
+  }
+  return documents;
+}
+async function findMarkdownPaths(projectRoot) {
+  const paths = [];
+  if (await fileExists(join3(projectRoot, "README.md"))) {
+    paths.push("README.md");
+  }
+  paths.push(...await findDocsMarkdownPaths(projectRoot));
+  return paths;
+}
+async function findDocsMarkdownPaths(projectRoot) {
+  const docsRoot = join3(projectRoot, "docs");
+  const paths = await findMarkdownPathsInDirectory(docsRoot);
+  return paths.map((path) => normalizePath2(relative2(projectRoot, path))).sort((first, second) => first.localeCompare(second));
+}
+async function findMarkdownPathsInDirectory(directory) {
+  let entries;
+  try {
+    entries = await readdir2(directory, { withFileTypes: true });
+  } catch (error) {
+    if (getErrorCode3(error) === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+  const paths = [];
+  for (const entry of entries.sort(
+    (first, second) => first.name.localeCompare(second.name)
+  )) {
+    const path = join3(directory, entry.name);
+    if (entry.isDirectory()) {
+      paths.push(...await findMarkdownPathsInDirectory(path));
+      continue;
+    }
+    if (entry.isFile() && entry.name.endsWith(".md")) {
+      paths.push(path);
+    }
+  }
+  return paths;
+}
+async function fileExists(path) {
+  try {
+    await readFile3(path, "utf8");
+    return true;
+  } catch (error) {
+    if (getErrorCode3(error) === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+function normalizePath2(path) {
+  return path.replace(/\\/g, "/");
+}
+function getErrorCode3(error) {
+  return typeof error === "object" && error !== null && "code" in error ? String(error.code) : void 0;
+}
+
+// src/report/formatReport.ts
+function formatReport(result) {
+  if (result.issues.length === 0) {
+    if (result.markdownDocuments.length === 0) {
+      return "DriftFence: no Markdown files found.";
+    }
+    return [
+      "DriftFence: no documentation drift found.",
+      `Checked ${result.markdownDocuments.map((document) => document.path).join(", ")}.`
+    ].join("\n");
+  }
+  const projectIssues = result.issues.filter(isProjectIssue);
+  const packageScriptIssues = result.issues.filter(isPackageScriptIssue);
+  const filePathIssues = result.issues.filter(isFilePathIssue);
+  const envVarIssues = result.issues.filter(isEnvVarIssue);
+  const lines = ["DriftFence found documentation drift.", ""];
+  appendSection(
+    lines,
+    "Project",
+    projectIssues.map((issue) => `- ${issue.message}`)
+  );
+  appendSection(
+    lines,
+    "Package scripts",
+    packageScriptIssues.map(
+      (issue) => `- \`${issue.command}\` in ${issue.path} references missing package.json script \`${issue.script}\`.`
+    )
+  );
+  appendSection(
+    lines,
+    "File paths",
+    filePathIssues.map(
+      (issue) => `- \`${issue.path}\` referenced in ${issue.markdownPath} does not exist.`
+    )
+  );
+  appendSection(
+    lines,
+    "Env vars",
+    envVarIssues.map(
+      (issue) => issue.source === "markdown" ? `- \`${issue.name}\` is mentioned in ${issue.path} but missing from .env.example.` : `- \`${issue.name}\` is used in ${issue.path} but missing from .env.example.`
+    )
+  );
+  lines.push("");
+  lines.push(`${result.issues.length} ${pluralize("issue", result.issues.length)} found.`);
+  return lines.join("\n");
+}
+function appendSection(lines, title, entries) {
+  if (entries.length === 0) {
+    return;
+  }
+  lines.push(`${title}:`);
+  lines.push(...entries);
+  lines.push("");
+}
+function isProjectIssue(issue) {
+  return issue.type === "package-json";
+}
+function isPackageScriptIssue(issue) {
+  return issue.type === "package-script";
+}
+function isFilePathIssue(issue) {
+  return issue.type === "file-path";
+}
+function isEnvVarIssue(issue) {
+  return issue.type === "env-var";
+}
+function pluralize(word, count) {
+  return count === 1 ? word : `${word}s`;
+}
+
+// src/index.ts
+async function checkProject(projectRoot = process.cwd()) {
+  const markdownDocuments = await readMarkdownDocuments(projectRoot);
+  const markdownReferences = markdownDocuments.flatMap(
+    (document) => document.references
+  );
+  if (markdownDocuments.length === 0) {
+    return {
+      projectRoot,
+      markdownDocuments,
+      markdownReferences,
+      issues: []
+    };
+  }
+  const [packageScriptIssues, filePathIssues, envVarIssues] = await Promise.all([
+    checkPackageScripts(projectRoot, markdownReferences),
+    checkFilePaths(projectRoot, markdownReferences),
+    checkEnvVars(projectRoot, markdownDocuments)
+  ]);
+  return {
+    projectRoot,
+    markdownDocuments,
+    markdownReferences,
+    issues: [...packageScriptIssues, ...filePathIssues, ...envVarIssues]
+  };
+}
+
+export {
+  checkPackageScripts,
+  findPackageScriptReferences,
+  checkFilePaths,
+  findFilePathReferences,
+  checkEnvVars,
+  findEnvExampleNames,
+  extractMarkdownText,
+  readMarkdownDocuments,
+  formatReport,
+  checkProject
+};

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+interface CliOutput {
+    stdout(message: string): void;
+    stderr(message: string): void;
+}
+declare function runCli(args?: string[], output?: CliOutput): Promise<number>;
+
+export { type CliOutput, runCli };

package/dist/cli.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+import {
+  checkProject,
+  formatReport
+} from "./chunk-4RCBAET6.js";
+
+// src/cli.ts
+import { stat } from "fs/promises";
+import { resolve } from "path";
+import { fileURLToPath } from "url";
+import cac from "cac";
+var defaultOutput = {
+  stdout: (message) => console.log(message),
+  stderr: (message) => console.error(message)
+};
+async function runCli(args = process.argv.slice(2), output = defaultOutput) {
+  const cli = cac("driftfence");
+  let exitCode = 0;
+  cli.command("check [projectDir]", "Check README.md for documentation drift").action(async (projectDir) => {
+    try {
+      const projectRoot = await resolveProjectRoot(projectDir);
+      const result = await checkProject(projectRoot);
+      output.stdout(formatReport(result));
+      exitCode = result.issues.length > 0 ? 1 : 0;
+    } catch (error) {
+      if (error instanceof ProjectDirectoryError) {
+        output.stderr(`DriftFence: ${error.message}`);
+        exitCode = 2;
+        return;
+      }
+      output.stderr(`DriftFence failed: ${getErrorMessage(error)}`);
+      exitCode = 1;
+    }
+  });
+  cli.help();
+  cli.parse([process.execPath, fileURLToPath(import.meta.url), ...args], {
+    run: false
+  });
+  if (!cli.matchedCommand && !args.some(isHelpArgument)) {
+    cli.outputHelp();
+    return 1;
+  }
+  await cli.runMatchedCommand();
+  return exitCode;
+}
+async function resolveProjectRoot(projectDir) {
+  const projectRoot = resolve(projectDir ?? process.cwd());
+  try {
+    const stats = await stat(projectRoot);
+    if (!stats.isDirectory()) {
+      throw new ProjectDirectoryError(
+        `Project path is not a directory: ${projectRoot}`
+      );
+    }
+    return projectRoot;
+  } catch (error) {
+    if (error instanceof ProjectDirectoryError) {
+      throw error;
+    }
+    if (getErrorCode(error) === "ENOENT") {
+      throw new ProjectDirectoryError(
+        `Project directory does not exist: ${projectRoot}`
+      );
+    }
+    throw error;
+  }
+}
+var ProjectDirectoryError = class extends Error {
+};
+function isDirectEntrypoint() {
+  return process.argv[1] ? resolve(process.argv[1]) === fileURLToPath(import.meta.url) : false;
+}
+function isHelpArgument(argument) {
+  return argument === "--help" || argument === "-h";
+}
+function getErrorCode(error) {
+  return typeof error === "object" && error !== null && "code" in error ? String(error.code) : void 0;
+}
+function getErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+if (isDirectEntrypoint()) {
+  process.exitCode = await runCli();
+}
+export {
+  runCli
+};

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+type MarkdownTextKind = "code" | "inlineCode";
+interface MarkdownTextReference {
+    kind: MarkdownTextKind;
+    value: string;
+}
+interface MarkdownTextReferenceWithPath extends MarkdownTextReference {
+    path: string;
+}
+declare function extractMarkdownText(markdown: string): MarkdownTextReference[];
+
+interface PackageScriptReference {
+    path: string;
+    command: string;
+    packageManager: "npm" | "pnpm" | "yarn";
+    script: string;
+}
+interface PackageScriptIssue {
+    type: "package-script";
+    path: string;
+    command: string;
+    script: string;
+}
+interface PackageJsonIssue {
+    type: "package-json";
+    path: string;
+    message: string;
+}
+type PackageScriptCheckIssue = PackageScriptIssue | PackageJsonIssue;
+declare function checkPackageScripts(projectRoot: string, references: MarkdownTextReferenceWithPath[]): Promise<PackageScriptCheckIssue[]>;
+declare function findPackageScriptReferences(references: MarkdownTextReferenceWithPath[]): PackageScriptReference[];
+
+interface FilePathReference {
+    path: string;
+    markdownPath: string;
+}
+interface FilePathIssue {
+    type: "file-path";
+    path: string;
+    markdownPath: string;
+}
+declare function checkFilePaths(projectRoot: string, references: MarkdownTextReferenceWithPath[]): Promise<FilePathIssue[]>;
+declare function findFilePathReferences(references: MarkdownTextReferenceWithPath[]): FilePathReference[];
+
+interface MarkdownDocument {
+    path: string;
+    content: string;
+    references: MarkdownTextReferenceWithPath[];
+}
+declare function readMarkdownDocuments(projectRoot: string): Promise<MarkdownDocument[]>;
+
+interface EnvVarIssue {
+    type: "env-var";
+    name: string;
+    source: "markdown" | "source";
+    path: string;
+}
+declare function checkEnvVars(projectRoot: string, markdownDocuments: MarkdownDocument[]): Promise<EnvVarIssue[]>;
+declare function findEnvExampleNames(content: string): Set<string>;
+
+declare function formatReport(result: CheckResult): string;
+
+type DriftIssue = PackageScriptCheckIssue | FilePathIssue | EnvVarIssue;
+interface CheckResult {
+    projectRoot: string;
+    markdownDocuments: MarkdownDocument[];
+    markdownReferences: MarkdownTextReferenceWithPath[];
+    issues: DriftIssue[];
+}
+declare function checkProject(projectRoot?: string): Promise<CheckResult>;
+
+export { type CheckResult, type DriftIssue, checkEnvVars, checkFilePaths, checkPackageScripts, checkProject, extractMarkdownText, findEnvExampleNames, findFilePathReferences, findPackageScriptReferences, formatReport, readMarkdownDocuments };

package/dist/index.js

@@ -0,0 +1,24 @@
+import {
+  checkEnvVars,
+  checkFilePaths,
+  checkPackageScripts,
+  checkProject,
+  extractMarkdownText,
+  findEnvExampleNames,
+  findFilePathReferences,
+  findPackageScriptReferences,
+  formatReport,
+  readMarkdownDocuments
+} from "./chunk-4RCBAET6.js";
+export {
+  checkEnvVars,
+  checkFilePaths,
+  checkPackageScripts,
+  checkProject,
+  extractMarkdownText,
+  findEnvExampleNames,
+  findFilePathReferences,
+  findPackageScriptReferences,
+  formatReport,
+  readMarkdownDocuments
+};

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "driftfence",
+  "version": "0.0.1",
+  "license": "MIT",
+  "keywords": [
+    "cli",
+    "documentation",
+    "readme",
+    "drift",
+    "docs",
+    "developer-tools",
+    "typescript"
+  ],
+  "description": "A CLI that catches outdated README commands, scripts, file references, and env vars.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "driftfence": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/cli.ts src/index.ts --format esm --dts --clean",
+    "demo:clean": "node ./dist/cli.js check ./tests/fixtures/basic-clean-project",
+    "demo:drift": "node ./dist/cli.js check ./tests/fixtures/basic-drift-project",
+    "dev": "tsx src/cli.ts",
+    "pack:dry": "npm pack --dry-run",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "test": "vitest run --pool=threads",
+    "typecheck": "tsc --noEmit"
+  },
+  "author": "Yakov Mulyavin",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CHAPAPOPA/driftfence.git"
+  },
+  "bugs": {
+    "url": "https://github.com/CHAPAPOPA/driftfence/issues"
+  },
+  "homepage": "https://github.com/CHAPAPOPA/driftfence#readme",
+  "dependencies": {
+    "cac": "^7.0.0",
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.5"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  }
+}