Generate a Docs report from a template

Document: one Drive file and document ID
  Tab: one tab ID, possibly with child tabs
    DocumentTab: the tab's document content
      Body
        Paragraph
          Text
        Table
          TableRow
            TableCell
              Paragraph
                Text

const SITE_REPORT = {
  templateId: 'REPLACE_WITH_TEMPLATE_DOCUMENT_ID',
  destinationFolderId: 'REPLACE_WITH_DESTINATION_FOLDER_ID',
  outputName: 'Harbor garden - site report',
  // Recovery only: the existing report you have inspected, never the template.
  confirmedOutputId: ''
};

/**
 * @typedef {{
 *   status: 'copy_pending'|'editing'|'complete',
 *   templateId: string,
 *   templateTabId: string,
 *   destinationFolderId: string,
 *   outputName: string,
 *   attemptedAt: string,
 *   paragraphs: string[],
 *   rows: string[][],
 *   outputId: string,
 *   outputTabId: string
 * }} SiteReportRecord
 */

const SITE_REPORT_RECORD_KEY = 'DOCS_SITE_REPORT';
const SITE_REPORT_MIME_TYPE = 'application/vnd.google-apps.document';

function inspectReportTemplate() {
  validateReportSettings_();
  const plan = prepareReport_();
  const destination = getReportDestination_();
  Logger.log('Template ID: ' + SITE_REPORT.templateId + '; tab ID: ' + plan.templateTabId);
  Logger.log('Destination: ' + destination.getName() + '; ID: ' + destination.getId());
  Logger.log('Planned paragraphs: ' + JSON.stringify(plan.paragraphs));
  Logger.log('Planned table: ' + JSON.stringify(plan.rows));
  showSiteReportRecord();
  Logger.log('Inspection only. No document contents or properties changed.');
}

function createSiteReport() {
  validateReportSettings_();
  withSiteReportLock_(() => {
    const previous = readSiteReportRecord_();
    if (previous !== null) {
      requireSameReportSettings_(previous);
      if (previous.status !== 'complete') {
        throw new Error('A report attempt is unresolved. Inspect DOCS_SITE_REPORT; do not create again.');
      }
      Logger.log('Already complete. No copy or content write. Output ID: ' + previous.outputId);
      Logger.log('Output URL: ' + DriveApp.getFileById(previous.outputId).getUrl());
      return;
    }

    const plan = prepareReport_();
    const destination = getReportDestination_();
    if (destination.getFilesByName(SITE_REPORT.outputName).hasNext()) {
      throw new Error('That output name already exists in the destination. Inspect it; no copy attempted.');
    }
    /** @type {SiteReportRecord} */
    const record = {
      status: 'copy_pending',
      templateId: SITE_REPORT.templateId,
      templateTabId: plan.templateTabId,
      destinationFolderId: SITE_REPORT.destinationFolderId,
      outputName: SITE_REPORT.outputName,
      attemptedAt: new Date().toISOString(),
      paragraphs: plan.paragraphs,
      rows: plan.rows,
      outputId: '',
      outputTabId: ''
    };
    // Preserve the plan and intent before the external copy. Never erase on error.
    saveSiteReportRecord_(record);
    const copy = plan.templateFile.makeCopy(record.outputName, destination);
    record.outputId = copy.getId();
    Logger.log('Drive returned output ID: ' + record.outputId);
    record.status = 'editing';
    // Save the output identity before any DocumentApp content mutation.
    saveSiteReportRecord_(record);
    renderRecordedReport_(record);
  });
}

function showSiteReportRecord() {
  const value = PropertiesService.getScriptProperties().getProperty(SITE_REPORT_RECORD_KEY);
  Logger.log(SITE_REPORT_RECORD_KEY + ': ' + (value === null ? 'No recorded attempt.' : value));
}

// Adopts an operator-confirmed existing copy. Does not create or edit a document.
function reconcileReportCopy() {
  validateReportSettings_();
  requireReportId_(SITE_REPORT.confirmedOutputId, 'confirmedOutputId');
  withSiteReportLock_(() => {
    const record = requireSiteReportRecord_();
    requireSameReportSettings_(record);
    if (record.status !== 'copy_pending') {
      if (record.outputId !== SITE_REPORT.confirmedOutputId) {
        throw new Error('A different output is already recorded. Do not replace its identity.');
      }
      Logger.log('That output is already recorded. No property or document changed.');
      return;
    }
    const file = requireReportOutput_(SITE_REPORT.confirmedOutputId, record);
    const document = DocumentApp.openById(file.getId());
    const tab = getSingleReportTab_(document);
    record.outputId = file.getId();
    record.outputTabId = tab.getId();
    record.status = 'editing';
    saveSiteReportRecord_(record);
    Logger.log('Existing copy recorded. Inspect it before choosing rebuildRecordedReport.');
  });
}

// DESTRUCTIVE TO THE RECORDED OUTPUT BODY: restores the saved plan, not annotations.
// The exact output ID must be typed into confirmedOutputId before this can run.
function rebuildRecordedReport() {
  validateReportSettings_();
  requireReportId_(SITE_REPORT.confirmedOutputId, 'confirmedOutputId');
  withSiteReportLock_(() => {
    const record = requireSiteReportRecord_();
    requireSameReportSettings_(record);
    if (record.status === 'copy_pending' || record.outputId !== SITE_REPORT.confirmedOutputId) {
      throw new Error('Confirm the recorded output ID; reconcile an unknown copy before rebuilding.');
    }
    renderRecordedReport_(record);
  });
}

function prepareReport_() {
  /** @type {{Project: string, Reporter: string, VisitDate: string, Summary: string}} */
  const replacements = {
    Project: SITE_REPORT_DATA.project,
    Reporter: SITE_REPORT_DATA.reporter,
    VisitDate: SITE_REPORT_DATA.visitDate,
    Summary: SITE_REPORT_DATA.summary
  };
  /** @type {Array<keyof typeof replacements>} */
  const replacementKeys = ['Project', 'Reporter', 'VisitDate', 'Summary'];
  for (const key of replacementKeys) {
    requireReportText_(replacements[key], key, 120);
  }
  const measurements = SITE_REPORT_DATA.measurements;
  if (!Array.isArray(measurements) || measurements.length < 1 || measurements.length > 3) {
    throw new Error('Supply 1-3 fictional measurements in Data.gs.');
  }
  const rows = [['Area', 'Planters', 'Note']];
  for (const item of measurements) {
    if (!item || typeof item !== 'object') throw new Error('Each measurement must be an object.');
    requireReportText_(item.area, 'area', 60);
    requireReportText_(item.note, 'note', 60);
    if (!Number.isInteger(item.planters) || item.planters < 0 || item.planters > 20) {
      throw new Error('planters must be an integer from 0 to 20.');
    }
    rows.push([item.area, String(item.planters), item.note]);
  }

  const templateFile = DriveApp.getFileById(SITE_REPORT.templateId);
  if (templateFile.isTrashed() || templateFile.getMimeType() !== SITE_REPORT_MIME_TYPE) {
    throw new Error('The template must be an untrashed Google Doc, not a shortcut.');
  }
  const document = DocumentApp.openById(SITE_REPORT.templateId);
  const tab = getSingleReportTab_(document);
  const body = tab.asDocumentTab().getBody();
  const count = body.getNumChildren();
  if (count !== 5 && count !== 6) {
    throw new Error('Use the five template paragraphs, with at most one empty trailing paragraph.');
  }
  const templateLines = [];
  for (let index = 0; index < count; index += 1) {
    const element = body.getChild(index);
    if (element.getType() !== DocumentApp.ElementType.PARAGRAPH) {
      throw new Error('The template body must contain only the supplied paragraphs, not lists or tables.');
    }
    const paragraph = element.asParagraph();
    if (paragraph.getNumChildren() > 12 || paragraph.getPositionedImages().length !== 0) {
      throw new Error('Use short, text-only template paragraphs without images.');
    }
    for (let child = 0; child < paragraph.getNumChildren(); child += 1) {
      if (paragraph.getChild(child).getType() !== DocumentApp.ElementType.TEXT) {
        throw new Error('Remove non-text elements from the practice template.');
      }
    }
    const text = paragraph.getText();
    if (index === 5 && text === '') continue;
    requireReportText_(text, 'template paragraph ' + (index + 1), 200);
    templateLines.push(text);
  }
  if (templateLines.length !== 5) throw new Error('The sixth template paragraph must be empty.');
  const requiredKeys = [['Project'], ['Project', 'Reporter'], ['VisitDate'], ['Summary'], []];
  const paragraphs = templateLines.map((line, index) => {
    /** @type {string[]} */
    const seen = [];
    const pattern = /\{\{([A-Za-z]+)\}\}/g;
    const withoutTokens = line.replace(pattern, '');
    if (withoutTokens.includes('{{') || withoutTokens.includes('}}')) {
      throw new Error('Malformed placeholder in template paragraph ' + (index + 1) + '.');
    }
    const filled = line.replace(pattern, (/** @type {string} */ match, /** @type {string} */ key) => {
      if (!requiredKeys[index].includes(key)) {
        throw new Error('Unexpected placeholder ' + match + ' in paragraph ' + (index + 1) + '.');
      }
      seen.push(key);
      // Callback results are literal, even when the value contains $& or backslashes.
      return reportReplacement_(key, replacements);
    });
    if (requiredKeys[index].some((key) => !seen.includes(key))) {
      throw new Error('A required placeholder is missing from paragraph ' + (index + 1) + '.');
    }
    requireReportText_(filled, 'filled paragraph', 500);
    return filled;
  });
  return { templateFile: templateFile, templateTabId: tab.getId(), paragraphs: paragraphs, rows: rows };
}

/**
 * @param {string} key
 * @param {{Project: string, Reporter: string, VisitDate: string, Summary: string}} replacements
 * @returns {string}
 */
function reportReplacement_(key, replacements) {
  switch (key) {
    case 'Project': return replacements.Project;
    case 'Reporter': return replacements.Reporter;
    case 'VisitDate': return replacements.VisitDate;
    case 'Summary': return replacements.Summary;
    default: throw new Error('Unexpected replacement key.');
  }
}

/**
 * @param {SiteReportRecord} record
 * @returns {void}
 */
function renderRecordedReport_(record) {
  const file = requireReportOutput_(record.outputId, record);
  const document = DocumentApp.openById(record.outputId);
  const tab = getSingleReportTab_(document);
  if (record.outputTabId !== '' && record.outputTabId !== tab.getId()) {
    throw new Error('The recorded output tab was replaced. Stop rather than edit another tab.');
  }
  record.outputTabId = tab.getId();
  record.status = 'editing';
  saveSiteReportRecord_(record);

  const body = tab.asDocumentTab().getBody();
  // This report owns the entire body. Reset it so a rebuild cannot append duplicates.
  body.setText(record.paragraphs[0]);
  for (let index = 0; index < record.paragraphs.length; index += 1) {
    const paragraph = index === 0
      ? body.getChild(0).asParagraph()
      : body.appendParagraph(record.paragraphs[index]);
    const heading = index === 0 ? DocumentApp.ParagraphHeading.TITLE
      : index === 4 ? DocumentApp.ParagraphHeading.HEADING2
      : DocumentApp.ParagraphHeading.NORMAL;
    paragraph.setHeading(heading).setSpacingAfter(8);
    paragraph.editAsText().setFontFamily('Arial')
      .setFontSize(index === 0 ? 20 : index === 4 ? 14 : 11)
      .setBold(index === 0 || index === 4)
      .setForegroundColor(index === 0 ? '#1F4E3D' : '#202124');
  }
  const table = body.appendTable(record.rows);
  table.setBorderWidth(1);
  for (let row = 0; row < record.rows.length; row += 1) {
    for (let column = 0; column < 3; column += 1) {
      const cell = table.getCell(row, column);
      cell.getChild(0).asParagraph().setHeading(DocumentApp.ParagraphHeading.NORMAL);
      cell.setBackgroundColor(row === 0 ? '#E8F0E9' : '#FFFFFF');
      cell.editAsText().setFontFamily('Arial').setFontSize(10)
        .setBold(row === 0).setForegroundColor('#202124');
    }
  }
  // Applies pending Docs changes; it is not a transaction with the property store.
  document.saveAndClose();
  record.status = 'complete';
  saveSiteReportRecord_(record);
  Logger.log('Report saved. Output ID: ' + record.outputId + '; tab ID: ' + record.outputTabId);
  Logger.log('Output URL: ' + file.getUrl());
}

/**
 * @param {DocumentApp.Document} document
 * @returns {DocumentApp.Tab}
 */
function getSingleReportTab_(document) {
  const tabs = document.getTabs();
  if (tabs.length !== 1 || tabs[0].getChildTabs().length !== 0 ||
      tabs[0].getType() !== DocumentApp.TabType.DOCUMENT_TAB) {
    throw new Error('Use exactly one document tab with no child tabs.');
  }
  const documentTab = tabs[0].asDocumentTab();
  const footnotes = documentTab.getFootnotes();
  if (documentTab.getHeader() !== null || documentTab.getFooter() !== null ||
      (footnotes !== null && footnotes.length !== 0)) {
    throw new Error('Use a practice document without headers, footers, or footnotes.');
  }
  return tabs[0];
}

/**
 * @param {string} id
 * @param {SiteReportRecord} record
 * @returns {DriveApp.File}
 */
function requireReportOutput_(id, record) {
  requireReportId_(id, 'outputId');
  if (id === record.templateId) throw new Error('The output cannot be the original template.');
  const destination = getReportDestination_();
  const file = DriveApp.getFileById(id);
  if (file.isTrashed() || file.getMimeType() !== SITE_REPORT_MIME_TYPE || file.getName() !== record.outputName) {
    throw new Error('Inspect the output: it must be an untrashed Google Doc with the recorded name.');
  }
  const parents = file.getParents();
  if (!parents.hasNext() || parents.next().getId() !== destination.getId() || parents.hasNext()) {
    throw new Error('The output must be directly in the recorded destination only.');
  }
  return file;
}

function getReportDestination_() {
  const folder = DriveApp.getFolderById(SITE_REPORT.destinationFolderId);
  if (folder.isTrashed()) throw new Error('Restore the intended destination folder from Trash.');
  return folder;
}

function validateReportSettings_() {
  requireReportId_(SITE_REPORT.templateId, 'templateId');
  requireReportId_(SITE_REPORT.destinationFolderId, 'destinationFolderId');
  if (SITE_REPORT.templateId === SITE_REPORT.destinationFolderId) {
    throw new Error('Use a document ID and a different folder ID.');
  }
  requireReportText_(SITE_REPORT.outputName, 'outputName', 80);
}

/**
 * @param {string} value
 * @param {string} label
 * @returns {void}
 */
function requireReportId_(value, label) {
  if (typeof value !== 'string' || value.startsWith('REPLACE_') ||
      value.length > 200 || !/^[A-Za-z0-9_-]+$/.test(value)) {
    throw new Error('Set ' + label + ' to the selected item ID, not a name or full URL.');
  }
}

/**
 * @param {string} value
 * @param {string} label
 * @param {number} limit
 * @returns {void}
 */
function requireReportText_(value, label, limit) {
  if (typeof value !== 'string' || value.trim().length === 0 || value.length > limit || /[\r\n\t]/.test(value)) {
    throw new Error(label + ' must be nonempty, single-line text of at most ' + limit + ' characters.');
  }
}

/**
 * @param {function(): void} action
 * @returns {void}
 */
function withSiteReportLock_(action) {
  const lock = LockService.getScriptLock();
  if (!lock.tryLock(1000)) throw new Error('Another report operation is running. Wait, then inspect the record.');
  try {
    action();
  } finally {
    lock.releaseLock();
  }
}

/**
 * @param {SiteReportRecord} record
 * @returns {void}
 */
function saveSiteReportRecord_(record) {
  PropertiesService.getScriptProperties().setProperty(SITE_REPORT_RECORD_KEY, JSON.stringify(record));
}

function readSiteReportRecord_() {
  const value = PropertiesService.getScriptProperties().getProperty(SITE_REPORT_RECORD_KEY);
  if (value === null) return null;
  /** @type {SiteReportRecord} */
  let record;
  try {
    record = JSON.parse(value);
  } catch (error) {
    throw new Error('The report record is unreadable. Preserve it; do not start over by deleting it.');
  }
  if (!record || typeof record !== 'object' || Array.isArray(record) ||
      !['copy_pending', 'editing', 'complete'].includes(record.status) ||
      typeof record.templateTabId !== 'string' || typeof record.outputTabId !== 'string' ||
      typeof record.attemptedAt !== 'string' || typeof record.outputId !== 'string') {
    throw new Error('Unexpected report record. Preserve it and investigate.');
  }
  requireReportId_(record.templateId, 'record.templateId');
  requireReportId_(record.destinationFolderId, 'record.destinationFolderId');
  requireReportText_(record.outputName, 'record.outputName', 80);
  if (!Array.isArray(record.paragraphs) || record.paragraphs.length !== 5 ||
      !Array.isArray(record.rows) || record.rows.length < 2 || record.rows.length > 4) {
    throw new Error('The saved report plan has an unexpected size. Preserve it.');
  }
  record.paragraphs.forEach((text) => requireReportText_(text, 'saved paragraph', 500));
  for (const row of record.rows) {
    if (!Array.isArray(row) || row.length !== 3) throw new Error('A saved table row must have three cells.');
    row.forEach((text) => requireReportText_(text, 'saved table cell', 60));
  }
  if (record.status === 'copy_pending') {
    if (record.outputId !== '' || record.outputTabId !== '') throw new Error('Unexpected pending-copy identity.');
  } else {
    requireReportId_(record.outputId, 'record.outputId');
    if (record.outputId === record.templateId) throw new Error('The record identifies the template as the output.');
    if (record.status === 'complete' && record.outputTabId === '') throw new Error('The completed record lacks its tab ID.');
  }
  return record;
}

function requireSiteReportRecord_() {
  const record = readSiteReportRecord_();
  if (record === null) throw new Error('No report attempt is recorded. Recovery cannot invent an attempt.');
  return record;
}

/**
 * @param {SiteReportRecord} record
 * @returns {void}
 */
function requireSameReportSettings_(record) {
  if (record.templateId !== SITE_REPORT.templateId ||
      record.destinationFolderId !== SITE_REPORT.destinationFolderId ||
      record.outputName !== SITE_REPORT.outputName) {
    throw new Error('Settings differ from the recorded attempt. Restore them before proceeding.');
  }
}

// Fictional data for one short report. No spreadsheet or external API is used.
const SITE_REPORT_DATA = {
  project: 'Harbor garden',
  reporter: 'Rowan',
  visitDate: '2026-09-11',
  summary: 'Twelve planters checked. Keep $25 for labels; file the sketch in Plans\\West.',
  measurements: [
    { area: 'North bed', planters: 6, note: 'Ready' },
    { area: 'Path edge', planters: 2, note: 'Needs soil' },
    { area: 'Courtyard', planters: 4, note: 'Water first' }
  ]
};

{
  "timeZone": "Etc/UTC",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/documents",
    "https://www.googleapis.com/auth/drive"
  ]
}