@pugi/cli 0.1.0-alpha.9 → 0.1.0-beta.2

package/dist/core/context/pugiignore.js

@@ -0,0 +1,316 @@
+/**
+ * `.pugiignore` parser - α6.5 Phase 1 (three-tier context).
+ *
+ * The CLI walks the workspace to build a repo skeleton and to feed the
+ * chokidar watcher. Both passes need a single source of truth for which
+ * paths are off-limits. `.pugiignore` extends (not replaces) `.gitignore`
+ * with Pugi-specific defaults: secret files, large binaries, build
+ * outputs, lockfiles.
+ *
+ * Design choices:
+ *
+ *   1. We layer four sources, last-write-wins per the .gitignore spec:
+ *      (a) Built-in DEFAULT_IGNORE_PATTERNS - secret / binary / build
+ *          paths every workspace should drop.
+ *      (b) `~/.pugi/global.pugiignore` - operator-global overrides.
+ *      (c) Repo `.gitignore` (when present) - so we don't re-walk
+ *          node_modules / dist / etc.
+ *      (d) Repo `.pugiignore` - workspace-local extensions.
+ *
+ *   2. The `ignore` npm package handles negation (`!path`) and nested
+ *      directories correctly. Rolling a minimal glob matcher is doable
+ *      but the test surface for gitignore semantics (esp. negation +
+ *      ancestor matching) is wide enough that pulling the audited
+ *      library is the safer call. It is already in the workspace via
+ *      transitive deps; we add it as an explicit pugi-cli dep.
+ *
+ *   3. Privacy is defense-in-depth: even if the operator deletes the
+ *      built-in defaults from their `.pugiignore`, we re-add the
+ *      secret patterns at the END of the chain so a typo in user
+ *      config cannot expose `.env` / `*.pem` / `*.key`. The user can
+ *      explicitly negate (`!.env.example`) but cannot wipe the
+ *      defense.
+ *
+ *   4. Paths are normalised to forward slashes (the `ignore` package
+ *      requires POSIX-style separators even on Windows) and stripped
+ *      of any leading workspace root so `isIgnored` answers in
+ *      repo-relative terms.
+ *
+ * The API surface is minimal: `loadPugiIgnore(cwd)` returns a
+ * `PugiIgnore` matcher with `isIgnored(absPath): boolean`. The matcher
+ * is built once at session bootstrap and reused by the skeleton walker
+ * and the chokidar watcher.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { relative, resolve, sep } from 'node:path';
+// The `ignore` package ships as CommonJS with `module.exports = factory`
+// plus a `.d.ts` that re-exports the factory as default. Under
+// `module: nodenext` TypeScript treats CJS default imports as the
+// `module.exports` shape, which for `ignore` IS the callable factory -
+// but only when we use the namespace-default dance below. A bare
+// `import ignore from 'ignore'` fails with "expression is not callable"
+// because TS resolves the import to the `typeof` shape rather than the
+// callable value.
+import * as ignoreModule from 'ignore';
+const ignoreFactory = ignoreModule.default
+    ?? ignoreModule;
+/**
+ * Built-in patterns shipped with every Pugi workspace. The list is a
+ * conservative union of three categories:
+ *
+ *   - **Secrets** (defense in depth): `.env*`, `*.pem`, `*.key`,
+ *     `secrets/**`, `.netrc`, `id_rsa*`, `*.secret`, `credentials*`.
+ *     These are re-applied at the END of the chain so user config
+ *     cannot accidentally expose them.
+ *
+ *   - **Build outputs / caches**: `node_modules/`, `dist/`, `build/`,
+ *     `.next/`, `.nuxt/`, `.svelte-kit/`, `coverage/`, `.nx/`, `.cache/`,
+ *     `.turbo/`, `.parcel-cache/`, `out/`, `.output/`, `*.tsbuildinfo`.
+ *
+ *   - **Large binaries / data**: lockfiles (`*.lock`, `*-lock.json`,
+ *     `*-lock.yaml`), images (`*.png`, `*.jpg`, `*.jpeg`, `*.gif`,
+ *     `*.ico`), PDFs, videos, archives (`*.zip`, `*.tar`, `*.gz`),
+ *     DB dumps (`*.sql`, `*.dump`), logs.
+ *
+ * The split between baseline patterns (applied first) and secret
+ * patterns (applied last) matters: a user `.pugiignore` can `!`-negate
+ * baseline entries (e.g. unignore a particular generated file under
+ * `dist/`) but cannot reach the trailing secret block. The trailing
+ * block is exported as `SECRET_IGNORE_PATTERNS` for tests.
+ */
+export const BASELINE_IGNORE_PATTERNS = Object.freeze([
+    // VCS / Pugi state
+    '.git/',
+    '.pugi/',
+    '.hg/',
+    '.svn/',
+    // Build outputs / package manager caches
+    'node_modules/',
+    '.pnpm-store/',
+    'dist/',
+    'build/',
+    'out/',
+    '.output/',
+    '.next/',
+    '.nuxt/',
+    '.svelte-kit/',
+    '.astro/',
+    'coverage/',
+    '.nyc_output/',
+    '.nx/',
+    '.turbo/',
+    '.parcel-cache/',
+    '.cache/',
+    '.vercel/',
+    '.netlify/',
+    '*.tsbuildinfo',
+    // Lockfiles - rebuilds, never agent-relevant
+    '*.lock',
+    'package-lock.json',
+    'yarn.lock',
+    'pnpm-lock.yaml',
+    'bun.lockb',
+    'composer.lock',
+    'poetry.lock',
+    'Cargo.lock',
+    'Gemfile.lock',
+    // Logs
+    '*.log',
+    'logs/',
+    '.pm2/',
+    // Large binaries
+    '*.png',
+    '*.jpg',
+    '*.jpeg',
+    '*.gif',
+    '*.ico',
+    '*.webp',
+    '*.bmp',
+    '*.tiff',
+    '*.svg',
+    '*.pdf',
+    '*.mp3',
+    '*.mp4',
+    '*.mov',
+    '*.webm',
+    '*.zip',
+    '*.tar',
+    '*.tar.gz',
+    '*.tgz',
+    '*.gz',
+    '*.bz2',
+    '*.7z',
+    '*.rar',
+    '*.dmg',
+    '*.iso',
+    // DB dumps / fixtures
+    '*.sql',
+    '*.dump',
+    '*.sqlite',
+    '*.sqlite3',
+    '*.db',
+    // OS noise
+    '.DS_Store',
+    'Thumbs.db',
+]);
+/**
+ * Secret patterns re-applied at the END of every layered chain. Even
+ * if the operator deletes these from `.pugiignore` (or accidentally
+ * negates them with `!.env`), the trailing block restores the gate.
+ * This is defense-in-depth: the skeleton walker MUST NOT read
+ * credentials into the agent context, period.
+ */
+export const SECRET_IGNORE_PATTERNS = Object.freeze([
+    '.env',
+    '.env.*',
+    '*.pem',
+    '*.key',
+    '*.crt',
+    '*.cert',
+    // X.509 cert formats - `*.cer` is the PEM-style cert extension common
+    // on Windows / Java keystores, `*.der` is the binary DER-encoded form
+    // used by Java + .NET tooling. Both can carry private keys when
+    // bundled (PKCS#7 / PKCS#12) and the file extension alone does not
+    // tell us whether the bundle includes a key. Treat as secrets by
+    // default. triple-review P1 (PR #380).
+    '*.cer',
+    '*.der',
+    '*.p12',
+    '*.pfx',
+    '*.jks',
+    '*.keystore',
+    'secrets/**',
+    '.netrc',
+    'id_rsa',
+    'id_rsa.*',
+    'id_ed25519',
+    'id_ed25519.*',
+    '*.secret',
+    'credentials',
+    'credentials.json',
+    'service-account*.json',
+    '*.kdbx',
+    '.aws/',
+    '.ssh/',
+    '.gnupg/',
+]);
+/**
+ * Where the operator's global ignore file lives. Mirrors the
+ * `~/.gitignore_global` convention. We do NOT auto-create it; if it
+ * exists, we load its non-empty / non-comment lines.
+ */
+export function globalPugiIgnorePath(home = homedir()) {
+    return resolve(home, '.pugi', 'global.pugiignore');
+}
+/** Path to the workspace `.pugiignore`. */
+export function workspacePugiIgnorePath(cwd) {
+    return resolve(cwd, '.pugiignore');
+}
+/** Path to the workspace `.gitignore`. */
+export function workspaceGitIgnorePath(cwd) {
+    return resolve(cwd, '.gitignore');
+}
+/**
+ * Load and compile the layered ignore matcher for `cwd`. The chain
+ * is built in this exact order so later layers override earlier ones,
+ * with the trailing secret block as the inviolable backstop:
+ *
+ *   1. BASELINE_IGNORE_PATTERNS  (built-in defaults)
+ *   2. ~/.pugi/global.pugiignore (operator global, optional)
+ *   3. <cwd>/.gitignore          (workspace, optional)
+ *   4. <cwd>/.pugiignore         (workspace, optional)
+ *   5. SECRET_IGNORE_PATTERNS    (defense-in-depth backstop)
+ *
+ * Any FS error reading optional files is swallowed - workspace
+ * context is best-effort and must never block the REPL bootstrap.
+ */
+export function loadPugiIgnore(cwd, options = {}) {
+    const home = options.home ?? homedir();
+    const normalisedCwd = resolve(cwd);
+    const patterns = [];
+    patterns.push(...BASELINE_IGNORE_PATTERNS);
+    const globalPath = globalPugiIgnorePath(home);
+    const globalPatterns = readPatternFile(globalPath);
+    patterns.push(...globalPatterns);
+    const gitignorePath = workspaceGitIgnorePath(normalisedCwd);
+    const gitPatterns = readPatternFile(gitignorePath);
+    patterns.push(...gitPatterns);
+    const pugiIgnorePath = workspacePugiIgnorePath(normalisedCwd);
+    const pugiPatterns = readPatternFile(pugiIgnorePath);
+    patterns.push(...pugiPatterns);
+    // Secrets last so they cannot be silently negated by user config.
+    patterns.push(...SECRET_IGNORE_PATTERNS);
+    const matcher = ignoreFactory().add(patterns);
+    return {
+        cwd: normalisedCwd,
+        patterns: Object.freeze(patterns.slice()),
+        isIgnored(absPath, isDir) {
+            return isIgnoredImpl(matcher, normalisedCwd, absPath, isDir === true);
+        },
+    };
+}
+/**
+ * Read a `.gitignore`-shaped file and return the non-comment / non-empty
+ * lines. Returns `[]` on any FS error. Lines are returned verbatim - the
+ * `ignore` library parses leading `!`, trailing `/`, and `**` correctly
+ * on its own.
+ */
+export function readPatternFile(path) {
+    try {
+        if (!existsSync(path))
+            return [];
+        const raw = readFileSync(path, 'utf8');
+        return parsePatternText(raw);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Pure parser for a `.gitignore`-shaped string. Splits on newlines,
+ * strips comment lines (`#`), trims whitespace, drops empty lines.
+ * Exported for the test suite so the chain is exercisable without a
+ * real filesystem.
+ */
+export function parsePatternText(raw) {
+    const lines = raw.split(/\r?\n/);
+    const out = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        if (trimmed.startsWith('#'))
+            continue;
+        out.push(trimmed);
+    }
+    return out;
+}
+/**
+ * Normalise an absolute path to a repo-relative POSIX path, then run
+ * it through the `ignore` matcher. Inputs outside the workspace return
+ * `false` - the matcher has no opinion about paths above its root.
+ */
+function isIgnoredImpl(matcher, cwd, absPath, isDir) {
+    const normalisedAbs = resolve(absPath);
+    if (normalisedAbs === cwd)
+        return false;
+    const rel = relative(cwd, normalisedAbs);
+    // Paths above the workspace root come back as `..` or `../foo`.
+    // The matcher has no opinion about those; treat as not-ignored.
+    if (rel.length === 0)
+        return false;
+    if (rel.startsWith('..'))
+        return false;
+    // `ignore` requires POSIX-style separators on every platform.
+    const posixRel = sep === '/' ? rel : rel.split(sep).join('/');
+    // Append a trailing slash for directories so gitignore-style
+    // dir patterns (`node_modules/`, `dist/`) match the dir itself,
+    // not just its children. Without this, `isIgnored('/abs/node_modules', true)`
+    // would return false because `ignore` only matches the child path
+    // shape for those patterns. See the spec for the failing case
+    // (skeleton walker descending into node_modules/).
+    const queryPath = isDir ? `${posixRel}/` : posixRel;
+    return matcher.ignores(queryPath);
+}
+//# sourceMappingURL=pugiignore.js.map