Postconditions: what we check

• readJson · file-not-found

  error
  WhenFile at path does not exist
  ThrowsError with code ENOENT
  Required handlingCaller MUST wrap in try-catch. Check error.code === 'ENOENT' to handle missing files. Consider using pathExists() first or providing a default value in the catch block.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• readJson · invalid-json

  error
  WhenFile exists but contains invalid JSON
  ThrowsSyntaxError
  Required handlingCaller MUST wrap in try-catch. Invalid JSON throws a SyntaxError (not an Error with a code). Validate JSON structure after reading if schema compliance is required.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• readJson · permission-denied

  error
  WhenProcess lacks read permission for the file
  ThrowsError with code EACCES
  Required handlingCaller MUST wrap in try-catch. Check error.code === 'EACCES' to handle permission errors. Ensure the process has appropriate filesystem permissions.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• copy · source-not-found

  error
  WhenSource path does not exist
  ThrowsError with code ENOENT
  Required handlingCaller MUST wrap in try-catch. Verify source exists before copying, or handle ENOENT in the catch block. Consider using pathExists() to pre-check source existence.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• copy · permission-denied

  error
  WhenProcess lacks read permission on source or write permission on destination
  ThrowsError with code EACCES
  Required handlingCaller MUST wrap in try-catch. Check error.code === 'EACCES' and handle appropriately. Ensure the process has read access to source and write access to destination parent.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• move · source-not-found

  error
  WhenSource path does not exist
  ThrowsError with code ENOENT
  Required handlingCaller MUST wrap in try-catch. Handle ENOENT for missing source path. Consider using pathExists() to pre-check source existence.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• move · destination-exists

  error
  WhenDestination already exists and overwrite option is not set to true
  ThrowsError: dest already exists.
  Required handlingCaller MUST either pass { overwrite: true } option to allow overwriting, or wrap in try-catch to handle the case where destination already exists. Note: the default for move (overwrite: false) differs from copy (overwrite: true) — a common footgun.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• move · permission-denied

  error
  WhenProcess lacks write permission on source or destination
  ThrowsError with code EACCES
  Required handlingCaller MUST wrap in try-catch. Check error.code === 'EACCES' and handle appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• outputFile · outputfile-permission-denied

  error
  WhenProcess lacks write permission on the target file or a parent directory component
  ThrowsError with code EACCES
  Required handlingCaller MUST wrap in try-catch. Check error.code === 'EACCES' to handle permission errors. SaaS apps often run as restricted users without write access to all paths. Particularly dangerous in background jobs where the error is silently discarded.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[4][5]
• outputFile · outputfile-disk-full

  error
  WhenFilesystem has no remaining space when fs.writeFile is called
  ThrowsError with code ENOSPC
  Required handlingCaller MUST wrap in try-catch. Check error.code === 'ENOSPC' to detect disk-full conditions. Unlike EACCES (predictable at startup), disk-full is a runtime error. Monitoring disk space and handling ENOSPC is critical for any app writing user files.
  costhighin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[4][5]
• writeJson · writejson-parent-not-found

  error
  WhenParent directory does not exist (writeJson does not create parent directories)
  ThrowsError with code ENOENT
  Required handlingCaller MUST wrap in try-catch. Unlike outputJson/outputFile, writeJson does NOT create missing parent directories. Use outputJson() if the parent directory may not exist. Handle ENOENT in the catch block to detect missing parent directories.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[6][7]
• writeJson · writejson-permission-denied

  error
  WhenProcess lacks write permission on the target file or parent directory
  ThrowsError with code EACCES
  Required handlingCaller MUST wrap in try-catch. Check error.code === 'EACCES' to handle permission errors. Propagates directly from fs.writeFile.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[6][7]
• writeJson · writejson-circular-reference

  error
  WhenData object contains circular references (e.g. ORM model, Express req/res object)
  ThrowsTypeError: Converting circular structure to JSON
  Required handlingCaller MUST wrap in try-catch. TypeError from circular references does not have a code property — check for TypeError or the message text. Avoid serializing ORM model instances, class objects with parent references, or Express req/res objects directly.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7][8]
• ensureDir · ensuredir-permission-denied

  error
  WhenProcess lacks write or execute permission on a parent directory component
  ThrowsError with code EACCES
  Required handlingCaller MUST wrap in try-catch. Check error.code === 'EACCES' to handle permission errors. Directory creation fails — subsequent file writes to that path will also fail with ENOENT. Ensure the process has write permission on all parent directory components.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[9][10]
• ensureDir · ensuredir-path-component-is-file

  error
  WhenA component of the path that should be a directory is actually an existing file
  ThrowsError with code ENOTDIR
  Required handlingCaller MUST wrap in try-catch. Check error.code === 'ENOTDIR' to detect path conflicts. This occurs in misconfigured deployments where a directory path collides with an existing file (e.g. '/data/config' is a file but caller expects a directory).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[9][10]
• remove · remove-permission-denied

  error
  WhenProcess lacks write permission on the file or directory, or execute permission on a parent directory
  ThrowsError with code EACCES (Unix) or EPERM (Windows)
  Required handlingCaller MUST wrap in try-catch. The force: true option ONLY silences ENOENT — it does NOT silence permission errors. Check error.code === 'EACCES' || error.code === 'EPERM'. Failed cleanup leaves orphaned files on disk with no alert.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[11][12][13]
• outputJson · outputjson-circular-reference

  error
  WhenData object contains circular references (e.g. ORM model instances, Express objects)
  ThrowsTypeError: Converting circular structure to JSON
  Required handlingCaller MUST wrap in try-catch. TypeError occurs before any file I/O — no file is created or modified. The error has no code property, making it harder to detect in generic catch blocks. Avoid serializing class instances or cyclic object graphs.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[14][7]
• outputJson · outputjson-permission-denied

  error
  WhenProcess lacks write permission on the target file or any parent directory
  ThrowsError with code EACCES
  Required handlingCaller MUST wrap in try-catch. Check error.code === 'EACCES'. Inherits from outputFile → fs.writeFile. Silent failure leaves system in stale state.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[14][5]
• ensureFile · ensurefile-permission-denied

  error
  WhenProcess lacks write permission on the target directory or execute permission on a parent
  ThrowsError with code EACCES
  Required handlingCaller MUST wrap in try-catch. Check error.code === 'EACCES'. Parent directory creation propagates EACCES unmodified. Common in init scripts that create log or pid files in permission-restricted paths.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[15][16]
• ensureFile · ensurefile-path-component-is-file

  error
  WhenA component of the path that should be a directory is actually an existing file
  ThrowsError with code ENOTDIR
  Required handlingCaller MUST wrap in try-catch. Check error.code === 'ENOTDIR'. The source explicitly calls fs.readdir(dir) to trigger ENOTDIR when the parent stat shows it is not a directory. Common in misconfigured deployments where a path component is a file, not a directory.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[16]
• mkdirp · mkdirp-permission-denied

  error
  WhenProcess lacks write or execute permission on a parent directory component
  ThrowsError with code EACCES
  Required handlingCaller MUST wrap in try-catch. Check error.code === 'EACCES' to handle permission errors. mkdirp() is identical to ensureDir() — both call fs.mkdir({recursive: true}) via makeDir. Directory creation fails — subsequent file writes to that path will also fail with ENOENT. Ensure the process has write permission on all parent directory components.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[9][10][17]
• mkdirp · mkdirp-path-component-is-file

  error
  WhenA component of the path that should be a directory is actually an existing file
  ThrowsError with code ENOTDIR
  Required handlingCaller MUST wrap in try-catch. Check error.code === 'ENOTDIR' to detect path conflicts. Same behavior as ensureDir() — a path component that exists as a file instead of a directory causes ENOTDIR from the underlying fs.mkdir({recursive: true}) call.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[9][10]
• mkdirs · mkdirs-permission-denied

  error
  WhenProcess lacks write or execute permission on a parent directory component
  ThrowsError with code EACCES
  Required handlingCaller MUST wrap in try-catch. Check error.code === 'EACCES' to handle permission errors. mkdirs() is identical to ensureDir() and mkdirp() — all call fs.mkdir({recursive: true}) via the same makeDir function. Directory creation failure will block all subsequent I/O at that path.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[9][10][17]
• mkdirs · mkdirs-path-component-is-file

  error
  WhenA component of the path that should be a directory is actually an existing file
  ThrowsError with code ENOTDIR
  Required handlingCaller MUST wrap in try-catch. Check error.code === 'ENOTDIR' to detect path conflicts. mkdirs() is identical to ensureDir() — same underlying fs.mkdir({recursive: true}) behavior.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[9][10]
• createFile · createfile-permission-denied

  error
  WhenProcess lacks write permission on the target directory or execute permission on a parent
  ThrowsError with code EACCES
  Required handlingCaller MUST wrap in try-catch. Check error.code === 'EACCES'. createFile() is the same underlying function as ensureFile() — both are exported as the same reference. Parent directory creation propagates EACCES from mkdir.mkdirs() unmodified. Common in init scripts that create log or pid files in permission-restricted paths.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[15][16][18]
• createFile · createfile-path-component-is-file

  error
  WhenA component of the path that should be a directory is actually an existing file
  ThrowsError with code ENOTDIR
  Required handlingCaller MUST wrap in try-catch. Check error.code === 'ENOTDIR'. The source explicitly calls fs.readdir(dir) to trigger ENOTDIR when the parent stat shows it is not a directory. createFile() is the same function as ensureFile() — identical ENOTDIR behavior.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[16]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.