driftfence 0.0.1 → 0.0.3

package/README.md

@@ -1,6 +1,7 @@
 # DriftFence
 
 [![CI](https://github.com/CHAPAPOPA/driftfence/actions/workflows/ci.yml/badge.svg)](https://github.com/CHAPAPOPA/driftfence/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/driftfence.svg)](https://www.npmjs.com/package/driftfence)
 
 Make sure your README doesn't lie.
 
@@ -8,7 +9,7 @@ DriftFence is a TypeScript Node.js CLI that catches outdated README and docs com
 
 ## Install
 
-Once published to npm:
+Install from npm:
 
 ```sh
 npm install -D driftfence
@@ -24,10 +25,14 @@ npx driftfence check
 
 Check a specific project directory:
 
+<!-- driftfence-ignore-start -->
+
 ```sh
 npx driftfence check ./path/to/project
 ```
 
+<!-- driftfence-ignore-end -->
+
 ## Example Output
 
 The local clean demo exits with code 0:
@@ -44,6 +49,8 @@ npm run demo:drift
 
 Example output from the drift fixture:
 
+<!-- driftfence-ignore-start -->
+
 ```text
 DriftFence found documentation drift.
 
@@ -60,19 +67,23 @@ Env vars:
 4 issues found.
 ```
 
+<!-- driftfence-ignore-end -->
+
 ## MVP Checks
 
-DriftFence checks `README.md` and `docs/**/*.md` for documentation drift.
+DriftFence checks `README.md` and `docs/**/*.{md,mdx}` for documentation drift.
 
 Current checks:
 
 - package script references
 - file path references
-- env var references in Markdown docs
+- env var references in Markdown and MDX docs
 - env var usage in source files
 
 Package script references include commands like:
 
+<!-- driftfence-ignore-start -->
+
 ```sh
 npm run build
 npm test
@@ -81,21 +92,31 @@ pnpm build
 yarn build
 ```
 
+<!-- driftfence-ignore-end -->
+
 Env var checks currently support references like:
 
+<!-- driftfence-ignore-start -->
+
 ```text
 API_URL
 DATABASE_URL
 VITE_API_URL
 ```
 
+<!-- driftfence-ignore-end -->
+
 and source usages like:
 
+<!-- driftfence-ignore-start -->
+
 ```ts
 process.env.API_URL
 import.meta.env.VITE_API_URL
 ```
 
+<!-- driftfence-ignore-end -->
+
 ## Exit Codes
 
 DriftFence uses stable CLI exit codes:
@@ -104,9 +125,27 @@ DriftFence uses stable CLI exit codes:
 - `1` — documentation drift found
 - `2` — invalid project directory or CLI usage error
 
+## Ignoring intentional examples
+
+Use ignore blocks when docs intentionally show fake paths, broken commands, fake env vars, or sample DriftFence output.
+
+````md
+<!-- driftfence-ignore-start -->
+
+```sh
+npm run missing-script
+```
+
+See `docs/missing.md`.
+Set `DATABASE_URL`.
+
+<!-- driftfence-ignore-end -->
+````
+
+Keep ignore blocks narrow so real setup instructions are still checked.
+
 ## Roadmap
 
-- MDX docs
 - GitHub Action
 - changed-files mode
 - configurable ignore rules
@@ -116,4 +155,4 @@ DriftFence uses stable CLI exit codes:
 
 AI features are not included in the MVP.
 
-DriftFence is deterministic-first: it checks concrete references in docs and code instead of guessing.
+DriftFence is deterministic-first: it checks concrete references in docs and code instead of guessing.

package/dist/{chunk-4RCBAET6.js → chunk-T6PL4YLE.js}

@@ -126,7 +126,7 @@ async function readPackageJson(projectRoot) {
     };
   }
   try {
-    return { packageJson: JSON.parse(rawPackageJson) };
+    return { packageJson: JSON.parse(stripBom(rawPackageJson)) };
   } catch (error) {
     return {
       issue: {
@@ -156,6 +156,9 @@ function normalizeCommand(command) {
 function hasOwn(object, key) {
   return Object.prototype.hasOwnProperty.call(object, key);
 }
+function stripBom(content) {
+  return content.startsWith("\uFEFF") ? content.slice(1) : content;
+}
 function getErrorCode(error) {
   return typeof error === "object" && error !== null && "code" in error ? String(error.code) : void 0;
 }
@@ -167,6 +170,30 @@ function getErrorMessage(error) {
 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;
+var javascriptDottedIdentifierRoots = /* @__PURE__ */ new Set([
+  "Array",
+  "Boolean",
+  "Buffer",
+  "Date",
+  "JSON",
+  "Map",
+  "Math",
+  "Number",
+  "Object",
+  "Promise",
+  "Reflect",
+  "RegExp",
+  "Set",
+  "String",
+  "Symbol",
+  "WeakMap",
+  "WeakSet",
+  "console",
+  "globalThis",
+  "import",
+  "module",
+  "process"
+]);
 async function checkFilePaths(projectRoot, references) {
   const pathReferences = findFilePathReferences(references);
   const issues = [];
@@ -196,6 +223,9 @@ function findFilePathReferences(references) {
 function findFilePathReferencesInText(text, markdownPath) {
   const references = [];
   for (const match of text.matchAll(pathTokenPattern)) {
+    if (isPartialDottedToken(text, match)) {
+      continue;
+    }
     const path = cleanPathCandidate(match[1]);
     if (!isLikelyFilePath(path)) {
       continue;
@@ -210,17 +240,83 @@ function cleanPathCandidate(candidate) {
   return withoutUrlSuffix.replace(/:\d+(?::\d+)?$/g, "").replace(/^\.\//, "");
 }
 function isLikelyFilePath(path) {
-  if (path.length === 0 || path.startsWith("@") || path.startsWith("-") || path.includes("://") || path.includes("*") || path.includes("$")) {
+  if (path.length === 0 || path.startsWith("@") || path.startsWith("-") || path.includes("://") || path.includes("*") || path.includes("$") || isUrlOrDomainLikeReference(path)) {
     return false;
   }
   if (!path.includes("/") && /^[A-Z][a-z]+(?:\.[a-z0-9]+)+$/.test(path)) {
     return false;
   }
+  if (isJavaScriptDottedIdentifier(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 isJavaScriptDottedIdentifier(path) {
+  if (path.startsWith(".") || path.includes("/") || path.includes("\\")) {
+    return false;
+  }
+  const parts = path.split(".");
+  return parts.length > 1 && javascriptDottedIdentifierRoots.has(parts[0] ?? "") && parts.every((part) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(part));
+}
+function isPartialDottedToken(text, match) {
+  const candidate = match[1] ?? "";
+  const matchText = match[0] ?? "";
+  const candidateStart = (match.index ?? 0) + Math.max(matchText.lastIndexOf(candidate), 0);
+  const candidateEnd = candidateStart + candidate.length;
+  return text[candidateEnd] === "." && /^[A-Za-z0-9_-]$/.test(text[candidateEnd + 1] ?? "");
+}
+function isUrlOrDomainLikeReference(path) {
+  return isUrlReference(path) || isEmailLikeReference(path) || isLocalhostReference(path) || isIpv4AddressReference(path) || isBareDomainReference(path);
+}
+function isUrlReference(path) {
+  return /^https?:\/\//i.test(path);
+}
+function isEmailLikeReference(path) {
+  return /^[^\s@/\\]+@[^\s@/\\]+\.[^\s@/\\]+$/.test(path);
+}
+function isLocalhostReference(path) {
+  return /^localhost(?::\d+)?(?:\/.*)?$/i.test(path);
+}
+function isIpv4AddressReference(path) {
+  return /^(?:\d{1,3}\.){3}\d{1,3}(?::\d+)?(?:\/.*)?$/.test(path);
+}
+function isBareDomainReference(path) {
+  if (path.startsWith(".") || path.includes("\\") || path.includes("@")) {
+    return false;
+  }
+  const host = path.split("/")[0] ?? "";
+  return isDomainHost(host);
+}
+var commonDomainSuffixes = /* @__PURE__ */ new Set([
+  "ai",
+  "app",
+  "biz",
+  "co",
+  "com",
+  "dev",
+  "edu",
+  "gov",
+  "info",
+  "io",
+  "me",
+  "net",
+  "online",
+  "org",
+  "site",
+  "tv",
+  "xyz"
+]);
+function isDomainHost(host) {
+  const withoutPort = host.replace(/:\d+$/, "");
+  const parts = withoutPort.split(".");
+  const suffix = parts.at(-1)?.toLowerCase();
+  return parts.length > 1 && suffix !== void 0 && commonDomainSuffixes.has(suffix) && parts.every(
+    (part) => /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/.test(part)
+  );
+}
 function uniquePathReferences(references) {
   const seen = /* @__PURE__ */ new Set();
   const uniqueReferences = [];
@@ -238,6 +334,52 @@ function uniquePathReferences(references) {
 // src/checkers/envVars.ts
 import { readFile as readFile2, readdir } from "fs/promises";
 import { join as join2, relative } from "path";
+
+// src/markdown/extractMarkdownText.ts
+import remarkParse from "remark-parse";
+import { unified } from "unified";
+var ignoreStart = "<!-- driftfence-ignore-start -->";
+var ignoreEnd = "<!-- driftfence-ignore-end -->";
+function extractMarkdownText(markdown) {
+  const tree = unified().use(remarkParse).parse(stripIgnoredMarkdownBlocks(markdown));
+  const references = [];
+  collectMarkdownText(tree, references);
+  return references;
+}
+function stripIgnoredMarkdownBlocks(markdown) {
+  let strippedMarkdown = "";
+  let position = 0;
+  while (position < markdown.length) {
+    const startIndex = markdown.indexOf(ignoreStart, position);
+    if (startIndex === -1) {
+      strippedMarkdown += markdown.slice(position);
+      break;
+    }
+    strippedMarkdown += markdown.slice(position, startIndex);
+    const endIndex = markdown.indexOf(
+      ignoreEnd,
+      startIndex + ignoreStart.length
+    );
+    if (endIndex === -1) {
+      break;
+    }
+    position = endIndex + ignoreEnd.length;
+  }
+  return strippedMarkdown;
+}
+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/checkers/envVars.ts
 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;
@@ -273,11 +415,13 @@ function findEnvExampleNames(content) {
 }
 function findMarkdownEnvVarReferences(document) {
   return uniqueEnvVarReferences(
-    [...document.content.matchAll(envVarPattern)].map((match) => ({
-      name: match[0],
-      source: "markdown",
-      path: document.path
-    }))
+    [...stripIgnoredMarkdownBlocks(document.content).matchAll(envVarPattern)].map(
+      (match) => ({
+        name: match[0],
+        source: "markdown",
+        path: document.path
+      })
+    )
   );
 }
 async function readEnvExampleNames(projectRoot) {
@@ -369,27 +513,6 @@ 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";
@@ -441,12 +564,15 @@ async function findMarkdownPathsInDirectory(directory) {
       paths.push(...await findMarkdownPathsInDirectory(path));
       continue;
     }
-    if (entry.isFile() && entry.name.endsWith(".md")) {
+    if (entry.isFile() && isMarkdownDocument(entry.name)) {
       paths.push(path);
     }
   }
   return paths;
 }
+function isMarkdownDocument(fileName) {
+  return fileName.endsWith(".md") || fileName.endsWith(".mdx");
+}
 async function fileExists(path) {
   try {
     await readFile3(path, "utf8");
@@ -567,9 +693,9 @@ export {
   findPackageScriptReferences,
   checkFilePaths,
   findFilePathReferences,
+  extractMarkdownText,
   checkEnvVars,
   findEnvExampleNames,
-  extractMarkdownText,
   readMarkdownDocuments,
   formatReport,
   checkProject

package/dist/cli.js

@@ -2,7 +2,7 @@
 import {
   checkProject,
   formatReport
-} from "./chunk-4RCBAET6.js";
+} from "./chunk-T6PL4YLE.js";
 
 // src/cli.ts
 import { stat } from "fs/promises";

package/dist/index.js

@@ -9,7 +9,7 @@ import {
   findPackageScriptReferences,
   formatReport,
   readMarkdownDocuments
-} from "./chunk-4RCBAET6.js";
+} from "./chunk-T6PL4YLE.js";
 export {
   checkEnvVars,
   checkFilePaths,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driftfence",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "license": "MIT",
   "keywords": [
     "cli",
@@ -41,6 +41,7 @@
     "dev": "tsx src/cli.ts",
     "pack:dry": "npm pack --dry-run",
     "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "self:check": "node ./dist/cli.js check .",
     "test": "vitest run --pool=threads",
     "typecheck": "tsc --noEmit"
   },
@@ -65,4 +66,4 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }
-}
+}