@debonet/idd 0.0.0-stage → 0.1.0

package/scripts/html-text.js

@@ -0,0 +1,50 @@
+// @tested-by test/idd-page.test.js
+// @implements s-tasgnp@85d6899
+// @implements s-yl6bcx@6415b0e
+// @implements s-irxy7e@fdc4d68
+const asEntityPlain = {
+  lt: "<",
+  gt: ">",
+  quot: "\"",
+  amp: "&",
+}
+
+const sReference = /&(#[0-9]+|#[xX][0-9a-fA-F]+|[a-zA-Z]+);/g
+
+const asEntityBody = {
+  lt: "<",
+  gt: ">",
+  quot: "\"",
+  apos: "'",
+  nbsp: " ",
+  amp: "&",
+}
+
+function fsCharacterFrom( asEntity ){
+  return ( sMatch, sName ) => {
+    if( sName[ 0 ] == "#" ){
+      const nCode = sName[ 1 ].toLowerCase() == "x"
+        ? parseInt( sName.slice( 2 ), 16 )
+        : parseInt( sName.slice( 1 ), 10 )
+      return Number.isNaN( nCode ) ? sMatch : String.fromCodePoint( nCode )
+    }
+    return sName in asEntity ? asEntity[ sName ] : sMatch
+  }
+}
+
+function fsDecoded( sText ){
+  return sText.replace( sReference, fsCharacterFrom( asEntityPlain ))
+}
+
+function fsText( sHtml ){
+  return sHtml
+    .replace( /<code>([\s\S]*?)<\/code>/g, "`$1`" )
+    .replace( /<br\s*\/?>/gi, "\n\n" )
+    .replace( /<\/?p(\s[^>]*)?>/gi, "\n\n" )
+    .replace( /<\/?[a-zA-Z][^>]*>/g, "" )
+    .replace( sReference, fsCharacterFrom( asEntityBody ))
+    .replace( /\n{3,}/g, "\n\n" )
+    .trim()
+}
+
+module.exports = { fsText, fsDecoded }

package/scripts/import-page.js

@@ -0,0 +1,80 @@
+// @tested-by test/idd-page.test.js
+// @implements s-hnxl58@6be6d28
+// @implements s-vhstia@aa7ed58
+const vm = require( "vm" )
+const { fsText, fsDecoded } = require( "./html-text" )
+const { faQuestionOptions } = require( "./check" )
+
+function fnArrayEnd( sSource, nStart ){
+  let nDepth = 0
+  let chQuote = null
+  for( let n = nStart; n < sSource.length; n++ ){
+    const ch = sSource[ n ]
+    if( chQuote ){
+      if( ch == "\\" ){
+        n++
+      } else if( ch == chQuote ){
+        chQuote = null
+      }
+    } else if( ch == "\"" || ch == "'" || ch == "`" ){
+      chQuote = ch
+    } else if( ch == "[" ){
+      nDepth++
+    } else if( ch == "]" && --nDepth == 0 ){
+      return n + 1
+    }
+  }
+  return -1
+}
+
+function fsArrayLiteral( sPage ){
+  const tMatch = /const\s+vaQuestion\s*=\s*(?=\[)/.exec( sPage )
+  if( !tMatch ){
+    throw new Error( "no vaQuestion array literal" )
+  }
+  const nStart = tMatch.index + tMatch[ 0 ].length
+  const nEnd = fnArrayEnd( sPage, nStart )
+  if( nEnd < 0 ){
+    throw new Error( "the vaQuestion array literal is not closed" )
+  }
+  return sPage.slice( nStart, nEnd )
+}
+
+function fvaEvaluated( sLiteral ){
+  let va
+  try {
+    va = new vm.Script( "(" + sLiteral + ")" ).runInNewContext(
+      Object.create( null ), { timeout: 1000 }
+    )
+  } catch( xError ){
+    throw new Error( "the vaQuestion array is unreadable: " + xError.message )
+  }
+  if( !Array.isArray( va )){
+    throw new Error( "vaQuestion is not an array" )
+  }
+  return va
+}
+
+function faOption( aOpt ){
+  const aNew = {
+    key: aOpt.sKey,
+    text: fsDecoded( String( aOpt.sText )),
+  }
+  const sTag = aOpt.sTag === undefined ? "" : fsDecoded( String( aOpt.sTag ))
+  return sTag ? { ...aNew, tag: sTag } : aNew
+}
+
+function faQuestion( aQ ){
+  return {
+    id: aQ.sId,
+    title: fsDecoded( String( aQ.sTitle )),
+    body: fsText( String( aQ.sBody )),
+    options: faQuestionOptions(( aQ.vaOpt || [] ).map( faOption )),
+  }
+}
+
+function fvaQuestionFromPage( sPage ){
+  return fvaEvaluated( fsArrayLiteral( sPage )).map( faQuestion )
+}
+
+module.exports = { fvaQuestionFromPage }

package/scripts/merge-hook.js

@@ -0,0 +1,365 @@
+// @tested-by test/merge-hook.test.js
+// @implements s-e4kj5b@8a40de4
+// @implements s-t0r5nn@6e7ef46
+// @implements s-sjb7rh@6c5ca7c
+// @implements s-02z196@0c73769
+// @implements s-sj7f9n@8b11936
+// @implements s-wjofsg@d016fd7
+// @implements s-fyoism@fc7783d
+const fs = require( "fs" )
+const path = require( "path" )
+const { spawnSync } = require( "child_process" )
+
+const sDirHooks = ".githooks"
+const sLineGate = '"$HOME/@concord/bin/spec-map" --gate || exit 1'
+const sLinePre = 'npm exec -- idd-merge-hook pre-commit || exit 1'
+const sLineMerge = 'npm exec -- idd-merge-hook pre-merge-commit || exit 1'
+const sLinePost = 'npm exec -- idd-merge-hook post-merge || exit 1'
+const sUsage = "usage: idd-merge-hook install|check|reviewed|pre-commit|pre-merge-commit|post-merge\n"
+
+class Git {
+  constructor( sRoot, sProgram ){
+    this.sRoot = sRoot
+    this.sProgram = sProgram
+  }
+
+  faRun( vsArgs, aOptions = {} ){
+    const aRun = spawnSync( this.sProgram, vsArgs, {
+      cwd: this.sRoot,
+      encoding: "utf8",
+      maxBuffer: 16 * 1024 * 1024,
+      ...aOptions,
+    })
+    if( aRun.error ) throw new Error( "cannot run git: " + aRun.error.message )
+    return { code: aRun.status, out: aRun.stdout || "", err: aRun.stderr || "" }
+  }
+
+  fs( vsArgs ){
+    const aRun = this.faRun( vsArgs )
+    if( aRun.code !== 0 ) throw new Error( aRun.err.trim() || "git " + vsArgs[ 0 ] + " failed" )
+    return aRun.out.trim()
+  }
+
+  fsTry( vsArgs ){
+    const aRun = this.faRun( vsArgs )
+    return aRun.code === 0 ? aRun.out.trim() : null
+  }
+
+  fRef( sRef ){
+    return this.fsTry([ "rev-parse", "--verify", "--quiet", sRef ])
+  }
+
+  fbAncestor( sOlder, sNewer ){
+    return this.faRun([ "merge-base", "--is-ancestor", sOlder, sNewer ]).code === 0
+  }
+}
+
+function fsAddLine( sText, sLine ){
+  if( sText.split( "\n" ).includes( sLine )) return sText.endsWith( "\n" ) ? sText : sText + "\n"
+  return ( sText && !sText.endsWith( "\n" ) ? sText + "\n" : sText ) + sLine + "\n"
+}
+
+function fWriteHook( sPath, sText ){
+  fs.mkdirSync( path.dirname( sPath ), { recursive: true })
+  fs.writeFileSync( sPath, sText, { mode: 0o755 })
+  fs.chmodSync( sPath, 0o755 )
+}
+
+function fInstall( git, sRoot, bConcord ){
+  const sHooksPath = git.fsTry([ "config", "--get", "core.hooksPath" ])
+  if( sHooksPath && sHooksPath !== sDirHooks ){
+    throw new Error( "core.hooksPath is " + sHooksPath + ", not " + sDirHooks )
+  }
+  if( !sHooksPath ){
+    const sCommon = git.fs([ "rev-parse", "--git-common-dir" ])
+    const sDefault = path.resolve( sRoot, sCommon, "hooks" )
+    for( const sName of [ "pre-commit", "pre-merge-commit", "post-merge" ] ){
+      if( fs.existsSync( path.join( sDefault, sName ))){
+        throw new Error( path.relative( sRoot, path.join( sDefault, sName )) +
+          " exists; refusing to disable that hook" )
+      }
+    }
+  }
+
+  const sDir = path.join( sRoot, sDirHooks )
+  const sPrePath = path.join( sDir, "pre-commit" )
+  let sPre = fs.existsSync( sPrePath ) ? fs.readFileSync( sPrePath, "utf8" ) : "#!/bin/sh\n"
+  if( bConcord ) sPre = fsAddLine( sPre, sLineGate )
+  sPre = fsAddLine( sPre, sLinePre )
+  fWriteHook( sPrePath, sPre )
+
+  for( const [ sName, sLine ] of [
+    [ "pre-merge-commit", sLineMerge ],
+    [ "post-merge", sLinePost ],
+  ]){
+    const sPath = path.join( sDir, sName )
+    const sText = fs.existsSync( sPath ) ? fs.readFileSync( sPath, "utf8" ) : "#!/bin/sh\n"
+    fWriteHook( sPath, fsAddLine( sText, sLine ))
+  }
+
+  if( sHooksPath !== sDirHooks ) git.fs([ "config", "core.hooksPath", sDirHooks ])
+}
+
+function fHookCheck( git, sRoot, bConcord ){
+  if( git.fsTry([ "config", "--get", "core.hooksPath" ]) !== sDirHooks ){
+    throw new Error( "core.hooksPath is not .githooks; run idd-merge-hook install" )
+  }
+  const aNeed = [
+    [ "pre-commit", sLinePre ],
+    [ "pre-merge-commit", sLineMerge ],
+    [ "post-merge", sLinePost ],
+  ]
+  if( bConcord ) aNeed.push([ "pre-commit", sLineGate ])
+  for( const [ sName, sLine ] of aNeed ){
+    const sPath = path.join( sRoot, sDirHooks, sName )
+    if( !fs.existsSync( sPath ) ) throw new Error( sPath + " is missing" )
+    if( !( fs.statSync( sPath ).mode & 0o111 )) throw new Error( sPath + " is not executable" )
+    const sText = fs.readFileSync( sPath, "utf8" )
+    if( !sText.split( "\n" ).includes( sLine )) throw new Error( sPath + " lacks its required IDD hook line" )
+  }
+}
+
+function fsReviewPath( git, sRoot ){
+  return path.resolve( sRoot, git.fs([ "rev-parse", "--git-path", "idd-merge-review.json" ]))
+}
+
+function fsCurrentBranch( git ){
+  return git.fsTry([ "symbolic-ref", "--quiet", "--short", "HEAD" ])
+}
+
+function faBranchesAt( git, sCommit, sExclude ){
+  const sRefs = git.fs([ "for-each-ref", "--format=%(refname:short)", "--points-at", sCommit,
+    "refs/heads", "refs/remotes" ])
+  const vsBranch = [ ...new Set( sRefs.split( "\n" ).filter( Boolean ).map(( sRef ) =>
+    sRef.startsWith( "origin/" ) ? sRef.slice( 7 ) : sRef
+  ).filter(( sBranch ) => !sBranch.startsWith( "idd-" ) && sBranch !== sExclude ))]
+  if( vsBranch.length ) return vsBranch
+  const sName = git.fsTry([ "name-rev", "--name-only", "--no-undefined", sCommit ])
+  if( !sName || sName === "undefined" ) return []
+  const sBranch = sName.replace( /~[0-9]+$/, "" ).replace( /\^[0-9]+$/, "" )
+    .replace( /^remotes\/origin\//, "" ).replace( /^origin\//, "" )
+  return sBranch && !sBranch.startsWith( "idd-" ) && sBranch !== sExclude
+    ? [ sBranch ] : []
+}
+
+function faIddRef( git, sCodeBranch ){
+  const sName = "idd-" + sCodeBranch
+  const sLocal = "refs/heads/" + sName
+  const sRemote = "refs/remotes/origin/" + sName
+  const sLocalSha = git.fRef( sLocal )
+  const sRemoteSha = git.fRef( sRemote )
+  if( !sLocalSha && !sRemoteSha ) return null
+  if( !sRemoteSha ){
+    return { problem: "the matching IDD branch " + sName + " is not published to origin" }
+  }
+  if( sLocalSha && !git.fbAncestor( sLocalSha, sRemoteSha )){
+    return { problem: "the local " + sName + " branch has commits that are not pushed to origin" }
+  }
+  return { name: sName, sha: sRemoteSha }
+}
+
+function faMergeContext( git, sSourceCommit, sTargetCommit = null ){
+  const sTargetBranch = fsCurrentBranch( git )
+  if( !sTargetBranch ) return { problem: "HEAD is detached; check out the target code branch first" }
+  const vsSource = faBranchesAt( git, sSourceCommit, sTargetBranch )
+  if( vsSource.length !== 1 ){
+    return { problem: "cannot identify the source code branch from " + sSourceCommit,
+      sourceCommit: sSourceCommit, targetBranch: sTargetBranch, sourceBranches: vsSource }
+  }
+  const sSourceBranch = vsSource[ 0 ]
+  const aSource = faIddRef( git, sSourceBranch )
+  const aTarget = faIddRef( git, sTargetBranch )
+  if( aSource && aSource.problem ) return { problem: aSource.problem,
+    sourceBranch: sSourceBranch, targetBranch: sTargetBranch }
+  if( aTarget && aTarget.problem ) return { problem: aTarget.problem,
+    sourceBranch: sSourceBranch, targetBranch: sTargetBranch }
+  if( !aSource && !aTarget ) return { none: true, sourceBranch: sSourceBranch, targetBranch: sTargetBranch }
+  if( !aSource || !aTarget ){
+    return { problem: "the matching IDD branch is missing; publish both `idd-" +
+      sSourceBranch + "` and `idd-" + sTargetBranch + "` before merging",
+      sourceBranch: sSourceBranch, targetBranch: sTargetBranch,
+      sourceIdd: aSource, targetIdd: aTarget }
+  }
+  return {
+    sourceBranch: sSourceBranch,
+    targetBranch: sTargetBranch,
+    sourceCommit: sSourceCommit,
+    targetCommit: sTargetCommit || git.fs([ "rev-parse", "HEAD" ]),
+    sourceIdd: aSource,
+    targetIdd: aTarget,
+  }
+}
+
+function faContextFromMerge( git, sPhase ){
+  let sSourceCommit = null
+  if( sPhase === "post-merge" ){
+    const vsParent = git.fs([ "rev-list", "--parents", "-n", "1", "HEAD" ]).split( " " )
+    sSourceCommit = vsParent.length > 2 ? vsParent[ 2 ] : null
+    if( sSourceCommit ) return faMergeContext( git, sSourceCommit, vsParent[ 1 ] )
+  } else {
+    sSourceCommit = git.fsTry([ "rev-parse", "--verify", "--quiet", "MERGE_HEAD" ])
+  }
+  if( !sSourceCommit ) return { none: true }
+  return faMergeContext( git, sSourceCommit )
+}
+
+function fsMergeSource( git, sPhase ){
+  if( sPhase === "post-merge" ){
+    const vsParent = git.fs([ "rev-list", "--parents", "-n", "1", "HEAD" ]).split( " " )
+    return vsParent.length > 2 ? vsParent[ 2 ] : null
+  }
+  return git.fsTry([ "rev-parse", "--verify", "--quiet", "MERGE_HEAD" ])
+}
+
+function faReview( git, sRoot ){
+  const aContext = faContextFromMerge( git, "reviewed" )
+  if( aContext.none ) return { already: true }
+  if( aContext.problem ) return { error: aContext.problem }
+  if( !git.fbAncestor( aContext.sourceIdd.sha, aContext.targetIdd.sha )){
+    return { error: "merge and reconcile the source IDD branch into the target IDD branch, then push it before recording the review" }
+  }
+  const sText = JSON.stringify({
+    sourceBranch: aContext.sourceBranch,
+    targetBranch: aContext.targetBranch,
+    sourceCommit: aContext.sourceCommit,
+    targetCommit: aContext.targetCommit,
+    sourceIdd: aContext.sourceIdd.sha,
+    targetIdd: aContext.targetIdd.sha,
+  }, null, 2 ) + "\n"
+  fs.writeFileSync( fsReviewPath( git, sRoot ), sText )
+  return { reviewed: true, context: aContext }
+}
+
+function fbReviewMatches( git, sRoot, aContext ){
+  try {
+    const aReview = JSON.parse( fs.readFileSync( fsReviewPath( git, sRoot ), "utf8" ))
+    return aReview.sourceBranch === aContext.sourceBranch &&
+      aReview.targetBranch === aContext.targetBranch &&
+      aReview.sourceCommit === aContext.sourceCommit &&
+      aReview.targetCommit === aContext.targetCommit &&
+      aReview.sourceIdd === aContext.sourceIdd.sha &&
+      aReview.targetIdd === aContext.targetIdd.sha
+  } catch( xError ){
+    return false
+  }
+}
+
+function fPrintMergeHold( fWriteErr, aContext, sDetail = "" ){
+  fWriteErr( "IDD branch reconciliation is required before this code merge.\n" )
+  fWriteErr( "Code source: " + ( aContext.sourceBranch || aContext.sourceCommit || "unknown" ) + "\n" )
+  fWriteErr( "Code target: " + ( aContext.targetBranch || "unknown" ) + "\n" )
+  if( aContext.sourceIdd ) fWriteErr( "IDD source: " + aContext.sourceIdd.name + " " + aContext.sourceIdd.sha + "\n" )
+  if( aContext.targetIdd ) fWriteErr( "IDD target: " + aContext.targetIdd.name + " " + aContext.targetIdd.sha + "\n" )
+  if( sDetail ) fWriteErr( sDetail + "\n" )
+  fWriteErr( "Compare both questionnaires and answers. Consolidate duplicates, obsolete questions and answer conflicts on the target IDD branch. Add and answer a clarifying question, and do its implementation, before resuming the code merge. If analysis finds no unresolved IDD work, run `npm exec -- idd-merge-hook reviewed` after the analysis.\n" )
+  return 1
+}
+
+function fCheckMerge( git, sRoot, sPhase, fWriteErr ){
+  if( !fsMergeSource( git, sPhase )) return 0
+  const aFetch = git.faRun([ "fetch", "origin" ])
+  if( aFetch.code !== 0 ){
+    fWriteErr( "IDD merge check could not fetch the latest questionnaire branches from origin.\n" +
+      aFetch.err )
+    return 1
+  }
+  const aContext = faContextFromMerge( git, sPhase )
+  if( aContext.none ) return 0
+  if( aContext.problem ) return fPrintMergeHold( fWriteErr, aContext )
+  if( !git.fbAncestor( aContext.sourceIdd.sha, aContext.targetIdd.sha )){
+    return fPrintMergeHold( fWriteErr, aContext,
+      "Merge and reconcile the source IDD branch into the target IDD branch, then push it." )
+  }
+  if( fbReviewMatches( git, sRoot, aContext )) return 0
+  return fPrintMergeHold( fWriteErr, aContext,
+    "The source IDD history is present, but an agent must review its meanings first." )
+}
+
+function fPostMerge( git, sRoot, fWriteErr ){
+  if( !fsMergeSource( git, "post-merge" )) return 0
+  const aFetch = git.faRun([ "fetch", "origin" ])
+  if( aFetch.code !== 0 ){
+    fWriteErr( "IDD post-merge could not fetch the latest questionnaire branches from origin.\n" +
+      aFetch.err )
+    return 1
+  }
+  const aContext = faContextFromMerge( git, "post-merge" )
+  if( aContext.problem ){
+    fWriteErr( "IDD post-merge could not identify the source and target branches: " + aContext.problem + "\n" )
+    return 1
+  }
+  if( aContext.none ) return 0
+  if( !git.fbAncestor( aContext.sourceIdd.sha, aContext.targetIdd.sha ) ||
+    !fbReviewMatches( git, sRoot, aContext )){
+    fWriteErr( "IDD post-merge found no matching reconciled and reviewed IDD state; reconcile " +
+      aContext.targetIdd.name + " manually.\n" )
+    return 1
+  }
+  try { fs.unlinkSync( fsReviewPath( git, sRoot )) } catch( xError ){}
+  return 0
+}
+
+function fvsUsage( fWriteErr ){
+  fWriteErr( sUsage )
+  return 2
+}
+
+function fzMain( vsArg, sCwd, fWrite, fWriteErr, aEnv = process.env ){
+  if( vsArg.length !== 1 || ![
+    "install", "check", "reviewed", "pre-commit", "pre-merge-commit", "post-merge",
+  ].includes( vsArg[ 0 ])) return fvsUsage( fWriteErr )
+  let sRoot
+  const git = new Git( sCwd, aEnv.IDD_GIT || "git" )
+  try {
+    sRoot = git.fs([ "rev-parse", "--show-toplevel" ])
+    git.sRoot = sRoot
+  } catch( xError ){
+    fWriteErr( "idd-merge-hook: " + xError.message + "\n" )
+    return 2
+  }
+  const bConcord = fs.existsSync( path.join( sRoot, "concord.json" ))
+  try {
+    switch( vsArg[ 0 ] ){
+      case "install":
+        fInstall( git, sRoot, bConcord )
+        fWrite( "IDD merge hooks installed in .githooks\n" )
+        return 0
+      case "check":
+        fHookCheck( git, sRoot, bConcord )
+        fWrite( "IDD merge hooks installed\n" )
+        return 0
+      case "reviewed": {
+        if( !fsMergeSource( git, "reviewed" )){
+          fWriteErr( "idd-merge-hook: reviewed can only be recorded while a code merge is in progress\n" )
+          return 1
+        }
+        const aFetch = git.faRun([ "fetch", "origin" ])
+        if( aFetch.code !== 0 ){
+          fWriteErr( "idd-merge-hook: could not fetch the latest questionnaire branches from origin\n" +
+            aFetch.err )
+          return 1
+        }
+        const aReview = faReview( git, sRoot )
+        if( aReview.error ){
+          fWriteErr( "idd-merge-hook: " + aReview.error + "\n" )
+          return 1
+        }
+        fWrite( aReview.already ? "IDD source data is already in the target branch\n"
+          : "IDD merge review recorded for the current merge\n" )
+        return 0
+      }
+      case "pre-commit":
+      case "pre-merge-commit":
+        return fCheckMerge( git, sRoot, vsArg[ 0 ], fWriteErr )
+      case "post-merge":
+        return fPostMerge( git, sRoot, fWriteErr )
+      default:
+        return fvsUsage( fWriteErr )
+    }
+  } catch( xError ){
+    fWriteErr( "idd-merge-hook: " + xError.message + "\n" )
+    return 2
+  }
+}
+
+module.exports = { fzMain }

package/scripts/page-build.js

@@ -0,0 +1,21 @@
+// @tested-by test/idd-page.test.js
+// @implements s-gcsqgg@1ad0f43
+// @implements s-t2pr4c@023afd8
+// @implements s-s1eg2z@e4283c0
+const fs = require( "fs" )
+const path = require( "path" )
+
+const sPathTemplate = path.join(
+  __dirname, "..", "templates", "questions-page.html"
+)
+
+function fsHtml( aPage, vaQuestion ){
+  const sJson = JSON.stringify(
+    { title: aPage.title, questions: vaQuestion }
+  ).replace( /</g, "\\u003c" )
+  return fs.readFileSync( sPathTemplate, "utf8" ).split( "__PAGE__" ).join(
+    sJson
+  )
+}
+
+module.exports = { fsHtml }

package/scripts/project-lock.js

@@ -0,0 +1,135 @@
+// @tested-by test/idd-page.test.js
+// @implements s-z8braj@8332190
+// @implements s-mm6l60@288776b
+// @implements s-qt9vvj@ddbf996
+// @implements s-zb5ycj@d0a620d
+const fs = require( "fs" )
+const path = require( "path" )
+
+const sDirLock = "tmp/idd"
+const msWaitMax = 10000
+const msPoll = 10
+const msStealStale = 2000
+
+function sleep( ms ){
+  Atomics.wait( new Int32Array( new SharedArrayBuffer( 4 )), 0, 0, ms )
+}
+
+function sUnique( sName ){
+  return sName + "-" + process.pid + "-" + Math.random().toString( 36 ).slice( 2 )
+}
+
+function fbAlive( nPid ){
+  try {
+    process.kill( nPid, 0 )
+    return true
+  } catch( xError ){
+    return xError.code === "EPERM"
+  }
+}
+
+function fsOwner( sDir ){
+  try {
+    return fs.readFileSync( path.join( sDir, "owner" ), "utf8" )
+  } catch( xError ){
+    return null
+  }
+}
+
+function removeDir( sDir, sDirParent ){
+  const sGone = path.join( sDirParent, sUnique( "gone" ))
+  try {
+    fs.renameSync( sDir, sGone )
+  } catch( xError ){
+    return
+  }
+  fs.rmSync( sGone, { recursive: true, force: true })
+}
+
+function steal( sLock, sDirParent ){
+  const sMutex = path.join( sDirParent, "steal" )
+  try {
+    fs.mkdirSync( sMutex )
+  } catch( xError ){
+    try {
+      if( Date.now() - fs.statSync( sMutex ).mtimeMs > msStealStale ){
+        fs.rmSync( sMutex, { recursive: true, force: true })
+      }
+    } catch( xInner ){
+      void xInner
+    }
+    return
+  }
+  try {
+    const sOwner = fsOwner( sLock )
+    if( sOwner !== null && !fbAlive( Number( sOwner ))){
+      removeDir( sLock, sDirParent )
+    }
+  } finally {
+    fs.rmSync( sMutex, { recursive: true, force: true })
+  }
+}
+
+function fbHeld( xError ){
+  return xError.code === "EEXIST" || xError.code === "ENOTEMPTY" ||
+    xError.code === "ENOTDIR"
+}
+
+function acquire( sRoot ){
+  const sDirParent = path.join( sRoot, sDirLock )
+  const sLock = path.join( sDirParent, "lock" )
+  const sOwn = path.join( sDirParent, sUnique( "own" ))
+  fs.mkdirSync( sOwn, { recursive: true })
+  fs.writeFileSync( path.join( sOwn, "owner" ), String( process.pid ))
+  const dtmStart = Date.now()
+  try {
+    for( ;; ){
+      try {
+        fs.renameSync( sOwn, sLock )
+        return sLock
+      } catch( xError ){
+        if( !fbHeld( xError )){
+          throw xError
+        }
+      }
+      steal( sLock, sDirParent )
+      if( Date.now() - dtmStart > msWaitMax ){
+        removeDir( sOwn, sDirParent )
+        return null
+      }
+      sleep( msPoll )
+    }
+  } catch( xError ){
+    removeDir( sOwn, sDirParent )
+    throw xError
+  }
+}
+
+function fxWithLock( sRoot, fx, fxBusy ){
+  const sLock = acquire( sRoot )
+  if( sLock === null ){
+    return fxBusy()
+  }
+  try {
+    return fx()
+  } finally {
+    const sDirParent = path.dirname( sLock )
+    removeDir( sLock, sDirParent )
+    try {
+      fs.rmdirSync( sDirParent )
+      try {
+        fs.rmdirSync( path.dirname( sDirParent ))
+      } catch( xError ){
+        if( xError.code !== "ENOTEMPTY" && xError.code !== "ENOENT" ){
+          throw xError
+        }
+      }
+    } catch( xError ){
+      if( xError.code !== "ENOTEMPTY" && xError.code !== "ENOENT" ){
+        throw xError
+      }
+    }
+  }
+}
+
+module.exports = { fxWithLock }